Join us at the Dash conference! July 16-17, NYC



This section explains what metrics are and what they do. Whether you want to send custom metrics, or have a better understanding about how Datadog works, read on. If you’re looking for information about the DogStatsD (which implements these metrics), see the DogStatsD documentation.

Submitting metrics

There are multiple ways to send metrics to Datadog:

  1. Via the Datadog Agent directly. Learn how to write an integration, or examine the Aggregator source code directly.
  2. Via the DogStatsD server (bundled with the Datadog Agent) and a client library.
  3. Directly via Datadog’s HTTP API.
  4. Via the Dropwizard Java metrics library with the metrics-datadog backend. Thanks to the people at Vistar Media, Coursera, and Bazaarvoice for their contributions.
Metric timestamps cannot be more than 10 minutes in the future or more than 1 hour in the past.

Naming metrics

There are a few rules regarding metric names:

  • Must start with a letter.
  • Must only contain ASCII alphanumerics, underscores, and periods.
    • Other characters, including spaces, are converted to underscores.
    • Unicode is not supported.
  • Must not exceed 200 characters. Fewer than 100 is preferred from a UI perspective.

Metrics reported by the Agent are in a pseudo-hierarchical dotted format (e.g. http.nginx.response_time). The hierarchy is neither enforced nor interpreted, but it can be used to infer things about servers. For example, if hostA and hostB are both reporting http.nginx.* those must be web frontends.

Metric Types

The “Datadog in-app type” affects how a given metric is interpreted in query results and graph visualizations across the application. This type is visible and can be changed on the metric summary page. Be aware that changing the metric type may render historical data nonsensical.

In the Datadog web application there are four metric types (though one is deprecated):

  • COUNTER (deprecated)
  • RATE

A metric’s type is stored as metrics metadata and is used to determine how a metric is interpreted throughout the application by determining default time aggregation function and as_rate()/as_count() behavior. The as_count() and as_rate() modifiers behave differently for different web application metric types.

Submission types and Datadog in-app types

Datadog accepts metrics submitted from a variety of sources, and as a result the “submission type” (think “use-case”) does not always map exactly to the Datadog in-app type:

Submission Source Submission Method (python) Submission Type Datadog In-App Type
API api.Metric.send(type="count", ...) count count
API api.Metric.send(type="gauge", ...) gauge gauge
API api.Metric.send(type="rate", ...) rate rate
DogStatsD dog.gauge(...) gauge gauge
DogStatsD dog.histogram(...) histogram gauge, rate
DogStatsD dog.increment(...) counter rate
DogStatsD dog.set(...) set gauge
Agent check self.count(...) count count
Agent check self.gauge(...) gauge gauge
Agent check self.histogram(...) histogram gauge, rate
Agent check self.increment(...) counter deprecated rate
Agent check self.monotonic_count(...) monotonic_count count
Agent check self.rate(...) rate gauge
Agent check self.set(...) set gauge

Modify a metric’s type

While it is not normally required, it is possible to change a metric’s type. For example:

  1. You have a metric app.requests.served that counts requests served, but accidentally submitted it via StatsD as a gauge. The metric’s Datadog type is therefore gauge.

  2. You wanted to submit app.requests.served as a StatsD count metric for time aggregation. This would help answer questions like “How many total requests were served in the past day?” by querying sum:app.requests.served{*} (this would not make sense for a gauge-type metric.)

  3. You like the name app.requests.served so rather than submitting a new metric name with the more appropriate count type, you could change the type of app.requests.served by updating:

    • Your submission code, calling dogstatsd.increment('app.requests.served', N) after N requests are served.
    • The Datadog in-app type via the metric summary page to rate.

This causes data submitted before the type change for app.requests.servedto behave incorrectly because it was stored in a format to be interpreted as an in-app gauge not a rate. Data submitted after steps 3a and 3b is interpreted properly.

If you are not willing to lose the historical data submitted as a gauge, create a new metric name with the new type, leaving the type of app.requests.served unchanged.

Note: For the AgentCheck, self.increment does not calculate the delta for a monotonically increasing counter, rather it reports the value passed in at the check run. To send the delta value on a monotonically increasing counter, use self.monotonic_count.


To eliminate ambiguity and help you make sense of your systems, the following units may be associated with metrics submitted to Datadog.

type unit(s)
BYTES bit / byte / kibibyte / mebibyte / gibibyte / tebibyte / pebibyte / exbibyte
TIME nanosecond / microsecond / millisecond / second / minute / hour / day / week
PERCENTAGE percent_nano / percent / apdex / fraction
NETWORK connection / request / packet / segment / response / message / payload / timeout / datagram / route / session
SYSTEM process / thread / host / node / fault / service / instance / cpu
DISK file / inode / sector / block
GENERAL buffer / error / read / write / occurrence / event / time / unit / operation / item / task / worker / resource / garbage collection / email / sample / stage / monitor / location / check / attempt / device / update / method / job / container / execution / throttle / invocation / user / success / build / prediction
DB table / index / lock / transaction / query / row / key / command / offset / record / object / cursor / assertion / scan / document / shard / flush / merge / refresh / fetch / column / commit / wait / ticket / question
CACHE hit / miss / eviction / get / set
MONEY dollar / cent
MEMORY page / split
FREQUENCY hertz / kilohertz / megahertz / gigahertz
TEMPERATURE degree celsius / degree fahrenheit
CPU nanocore / microcore / millicore / core / kilocore / megacore / gigacore / teracore / petacore / exacore

Units are displayed automatically on timeseries graphs, query value widgets, and toplists, as shown in the screenshot of the Redis dashboard below:

Redis dash metric units

On timeseries graphs, move your cursor over any graph to see the relevant units. The raw data is automatically converted to readable display units (fractions of a second to ms, millions of bytes per second to MiB/s, etc.):

postgres commits

Units are also displayed at the bottom of timeboard graphs, and metric descriptions are available by selecting Metrics Info from the gear dropdown:

Annotated ops

Further reading