datadog/documentation

The source for Datadog's documentation site.

documentation's Issues

The difference between graphite metric queries and datadog

In terms of metric naming, we differ a little with Graphite in that a metric query is defined by a metric name and a scope, where a scope is one or more tags. To translate:

<application>.requests.<HTTP Method>.<Handler Class>.<Handler Method>.mean_90

into Datadog, we'd probably say:

<application>.requests.mean_90{http_method:<HTTP Method>, handler_class:<Handler Class>, handler_method:<Handler Method>}

Where <application>.requests.mean_90 is the metric name, and http_method:, handler_class:, handler_method: are tags, so a concrete example might look like:

sync.requests.mean_90{http_method:GET, handler_class:ItemHandler, handler_method:list}

To do aggregation, we can specify an aggregator as part of the metric query:

avg:sync.requests.mean_90{http_method:GET, handler_class:ItemHandler, handler_method:list}

This will graph a single series that's the average of that metric across the intersection of those tags. We support avg, sum, min, max aggregators. If you wanted to see all the possible series for a given tag facet, you can say:

avg:sync.requests.mean_90{handler_class:ItemHandler, handler_method:list} by {http_method}

Which would graph stacked area series for each http_method value like GET, POST, etc.

API navigation bar should always be visible

I like the way the sidebar stays visible for the guides. It would be great it the same was true of the API Reference bar so I could switch languages and jump around without scrolling back to the top.

Add host aliasing guide/configuration to agent docs.

Not properly configuring your fqdn will cause unwated aliasing.

What are valid tags?

Metric names must start with a letter, and after that may contain alphanumerics, underscores, minuses, colons, periods and slashes. Other characters will get converted to underscores. Tags can be up to 200 characters long and support unicode.

How to extract metrics/events from logs

Already docs on this, just needs to be part of the guide's index

http://pydoc.datadoghq.com/en/latest/ links to dashboard documentation are broken

They point to the old api.datadoghq.com site.

Add the AgentCheck constructor interface to the guide.

clean up home page

Document the alert API

The code is already there, and it's a pretty simple API. So we should document it.

make the bootstrap theme more purple

finish libraries page

Document how aggregation_key works

add curl api examples

home page should have a small hello world example

Right now when you go to docs.datadoghq.com, you need to click on another link to see what the site is about. I like how Sinatra does it where there's a minimal hello world example, then links for more indepth docs.

How to slice metrics on different dimensions

• Set up tagging
• Graph editor

Why you should collect metrics and events

Potentially large topic. Maybe gather lots of resources from the web. Maybe throw some allspaw and codahale talks

How do I get the list of hosts and their IDs?

Other API endpoints require the host_id to be passed, yet there is no clear way to get these IDs without clicking around on the infrastructure overview.

This will drive API changes, but it's probably a good place to start.

What operational metrics are important for web services?

Explain throughput, latency, error rate.

How do I modify the command that starts the agent?

centos5:

/etc/init.d/datadog-agent

centos6:

/etc/dd-agent/supervisor.conf

deb/ubuntu:

/etc/supervisor/conf.d/ddagent.conf

Added dog cli examples to the API page.

So that is documented somewhere.

Where is datadog.conf located?

*nix: /etc/dd-agent/datadog.conf
osx (source install): ~/.datadog-agent/agent/datadog.conf
Windows 2008: C:\ProgramData\Datadog
Windows (other): C:\Documents and Settings\All Users\Application Data\Datadog\

Duplicate "happened"

In Counters:

Counters

Counters track how many times something _happened happened_, like the number of database requests or page views.

dog.increment('database.query.count')
dog.increment('page_view.count', 10)

Update Guide to Log Parsing to mention class-based dogstreams

A recent addition to the agent, dogstreams can use classes in addition to functions to parse logs. Useful when needing stateful parsing with initialization.

How to track changes for each release

Similar to Datadog's release event with the diff link

How to correlate events with metrics

• graph editor search value
• stream on dash

Alert api docs don't explain the syntax

Covering simple and multi-alerts:

• query syntax
• notify_no_data
• auto-resolution

add dogstatsd performance numbers

• how many points you can send per second
• performance characteristics, etc.

How do use Datadog on the go

No mobile, but you can reply to emails and they'll become comments

What are valid metric names?

Metric names must start with a letter, and after that may contain ascii alphanumerics, underscore and periods. Other characters will get converted to underscores. There is no max length

How to track cron runs

Need to actually implement this

How to get notifications when things happen

• @ mention syntax in events
• metric alerts

dogstatsd: clarify counters & make flush_interval more prominent

Need a clear example with calling increment() multiple times during a flush interval and not calling it all. Also explain how it is different from distributed counters (i.e. there is no state kept between calls if data get flushed).

How to instrument your code without taking a performance hit

• dogstatsd
• logging + agent log parser

dogstatsd guide doesn't explain what kind of data you should expect to see in datadog

ie, how the aggregation works, how many points you should see etc

What operational metrics are important for queueing?

• size of the queue
• queue processing throughput
• length of time spent in queue
• error rate in processing

How do I share graphs on other sites?

currently we allow the embedding of specific graphs on other sites
if you open the editor on the graph you want to share, and click on the Share tab
you can generate an html snippet you can put on other sites

add ruby api examples

How to submit lots of related events

• various event inputs
• aggregation key

Is datadog a cloud service or desktop application?

It's primarily a cloud service, but in order to collect data on your servers, there is an agent you'll need to install.

Move graph primer to new docs

http://help.datadoghq.com/kb/graphs-dashboards/graph-primer

Fix API title so that it shows up nicely on google

How do I get disk usage as a percentage instead of in bytes?

Use system.disk.in_use, collected by the agent.

How do I collect custom WMI metrics (Windows)

https://github.com/DataDog/dd-agent/blob/master/datadog.conf.example#L411-L421

How do I get the version of the agent?

On linux, < 3.4.0:

cd /usr/share/datadog/agent && python -c 'import config; print config.get_version()'

Linux, >= 3.4.0:

/etc/init.d/datadog-agent status

Windows: ...

align language choice with code blocks on the api docs

Windows: interactively test the agent

Run the agent's shell by navigating to C:\Program Files (x86)\Datadog\Datadog Agent and running shell.exe. From here you can run parts of the agent.

To test IIS:

ipaddress = 'blah'
import wmi
w = wmi.WMI(ipaddress, user=None, password=None)
wmi_cls = w.Win32_PerfFormattedData_W3SVC_WebService(name="_Total")[0]
print wmi_cls.BytesSentPerSec

Document the metric query language and data model

For example, the differences between functions and aggregators:

Yes, min, max and avg aren't functions per se, they're aggregators. We haven't documented our model as well as we should, but we consider functions as transforms of a single metric series, whereas aggregators combine many metric series's across tags. For example, if we had a metric called foo with values:

host:a = 1,1,4,1,1
host:b = 2,2,0,2,2

Using the min aggregator like min:foo{*} would turn the two series into a single series:

1,1,0,1,1

If we added a min function like min(foo{host:a}), we would get just a single value of 1.

If we had min(foo{*}), we'd still need an aggregator, in this case avg is assumed, so that would be:

avg:foo{} = 1.5, 1.5, 2, 1.5, 1.5
min(avg:foo{}) = 1.5

If we wanted the hosts in tact, we would say min(foo{*} by {host}), then we'd apply the function to each series:

min(host:a) = 1
min(host:b) = 0

add a getting started homepage

• links to "guide to metrics"
• links to "guide to graphs"
• etc

see stripe's docs for a great example.

Most of my hosts can't connect to the internet directly, how do I set up the agent?

Need to set dd_url in datadog.conf to a host in your data center that is allowed to connect to datadoghq.com directly, then update the file that runs the agent (see #54) to remove --use-local-forwarder so that it uses the dd_url value instead of localhost.

Document the agent watchdog

If you don't know any better, it seems like a crashing bug on our end