Each metric submitted to Datadog should have a type. A metric’s type affects how the metric values are displayed when queried, as well as the associated graphing possibilities within Datadog using additional modifiers and functions. A metric’s type is displayed on the details side panel for the given metric on the Metrics Summary page.
Note: Changing the metric type in this details side panel can change metric behavior in all existing visualizations and monitors, potentially rendering historical data as nonsensical.
The following metric submission types are accepted:
These different metric submission types are mapped to four in-app metric types found within the Datadog web application:
Note: If you submit a metric to Datadog without a type, the metric type appears as Not Assigned within Datadog. The Not Assigned metric type cannot be further changed to another in-app type until an initial metric type is submitted.
Metrics are submitted to Datadog in three main ways:
The majority of data that Datadog receives is submitted by the Agent, either through an Agent check or DogStatsD. For these submission methods, a metric’s type determines how multiple values collected on an Agent in a flush time interval are aggregated. The Agent combines these values into a single representative metric value for that interval. This combined value is stored with a single timestamp in Datadog.
Data submitted directly to the Datadog API is not aggregated by Datadog, with the exception of distribution metrics. The raw values sent to Datadog are stored as-is.
Read the Submission types and Datadog in-app types section to learn about how different metric submission types are mapped to their corresponding in-app types.
The COUNT metric submission type represents the total number of event occurrences in one time interval. A COUNT can be used to track the total number of connections made to a database or the total number of requests to an endpoint. This number of events can accumulate or decrease over time—it is not monotonically increasing.
Note: A COUNT is different from the RATE metric type, which represents the number of event occurrences normalized per second given the defined time interval.
The RATE metric submission type represents the total number of event occurrences per second in one time interval. A RATE can be used to track how often something is happening—like the frequency of connections made to a database or the flow of requests made to an endpoint.
Note: A RATE is different from the COUNT metric submission type, which represents the total number of event occurrences in the given time interval.
The GAUGE metric submission type represents a snapshot of events in one time interval. This representative snapshot value is the last value submitted to the Agent during a time interval. A GAUGE can be used to take a measure of something reporting continuously—like the available disk space or memory used.
The HISTOGRAM metric submission type represents the statistical distribution of a set of values calculated Agent-side in one time interval. Datadog’s HISTOGRAM metric type is an extension of the StatsD timing metric type. The Agent aggregates the values that are sent in a defined time interval and produces different metrics which represent the set of values.
If you send X values for a HISTOGRAM metric <METRIC_NAME> in a given time interval, the following metrics are produced by the Agent by default:
<METRIC_NAME>.avgX values in the time interval.<METRIC_NAME>.countX. The Agent submits this number as a RATE so it would show in app the value of X/interval.<METRIC_NAME>.medianX values in the time interval.<METRIC_NAME>.95percentileX values in the time interval.<METRIC_NAME>.maxX values sent during the time interval.Note:
histogram_aggregates parameter in your datadog.yaml configuration file. By default, only max, median, avg, and count aggregations are sent to Datadog. sum and min are also available.histogram_percentiles parameter in your datadog.yaml configuration file. By default, only the 95percentile is sent to Datadog.The DISTRIBUTION metric submission type represents the global statistical distribution of a set of values calculated across your entire distributed infrastructure in one time interval. A DISTRIBUTION can be used to instrument logical objects, like services, independently from the underlying hosts.
Unlike the HISTOGRAM metric type, which aggregates on the Agent during a given time interval, a DISTRIBUTION metric sends all the raw data during a time interval to Datadog. Aggregations occur on the server-side. Because the underlying data structure represents raw, unaggregated data, distributions provide two major features:
If you send X values for a DISTRIBUTION metric <METRIC_NAME> in a given time interval, the following aggregations are available for query by default:
avg:<METRIC_NAME>X values in the time interval.count:<METRIC_NAME>X. The Agent then sends it as a COUNT.max:<METRIC_NAME>X values sent in the time interval.min:<METRIC_NAME>X sent in the time interval.sum:<METRIC_NAME>X values sent in the time interval.Suppose you are submitting a COUNT metric, activeusers.basket_size, from a single host running the Datadog Agent. This host emits the following values in a flush time interval: [1,1,1,2,2,2,3,3].
The Agent adds all of the values received in one time interval. Then, it submits the total number, in this case 15, as the COUNT metric’s value.
Suppose you are submitting a RATE metric, queue_messages.rate, from a single host running the Datadog Agent. This host emits the following values in a flush time interval: [1,1,1,2,2,2,3,3].
The Agent adds all of the values received in one time interval. Then, it submits the total number divided by the total number of seconds in this time interval. In this case, if the flush interval is 10 seconds, the value submitted would be 1.5 as the RATE metric’s value.
Suppose you are submitting a GAUGE metric, temperature, from a single host running the Datadog Agent. This host emits the following values in a flush time interval: [71,71,71,71,71,71,71.5].
The Agent submits the last reported number, in this case 71.5, as the GAUGE metric’s value.
For example, suppose you are submitting a HISTOGRAM metric, request.response_time.histogram, from a web server that reports the values [1,1,1,2,2,2,3,3] in a flush time interval. By default, the Agent submits the following metrics to Datadog which represent the statistical distribution of these values in this time interval:
request.response_time.histogram.avg1.88GAUGErequest.response_time.histogram.count0.8RATErequest.response_time.histogram.median2GAUGErequest.response_time.histogram.95percentile3GAUGErequest.response_time.histogram.max3GAUGESuppose you are submitting a DISTRIBUTION metric, request.response_time.distribution, from two webservers: webserver:web_1 and webserver:web_2. Suppose in a given flush time interval, webserver:web_1 reports the metric with the values [1,1,1,2,2,2,3,3], and webserver:web_2 reports the same metric with the values [1,1,2]. Over this time interval, the following five aggregations will represent the global statistical distribution of all values collected from both webservers:
avg:request.response_time.distribution1.73GAUGEcount:request.response_time.distribution11COUNTmax:request.response_time.distribution3GAUGEmin:request.response_time.distribution1GAUGEsum:request.response_time.distribution19COUNTLike other metric types, such as GAUGE or HISTOGRAM, the DISTRIBUTION metric type has the following aggregations available: count, min, max, sum, and avg. Distribution metrics are initially tagged the same way as other metrics (with custom tags set in the code).
Additional percentile aggregations (p50, p75, p90, p95, p99) can be added to distribution metrics. If you were to add percentile aggregations to your distribution metric in-app, the following five additional aggregations are available for query:
p50:request.response_time.distribution2GAUGEp75:request.response_time.distribution2GAUGEp90:request.response_time.distribution3GAUGEp95:request.response_time.distribution3GAUGEp99:request.response_time.distribution3GAUGEThat is, for a distribution metric with added percentile aggregations during a given time interval, the following 10 aggregations are available: count, sum, min, max, avg, p50, p75, p90, p95, and p99.
This functionality allows you to control tagging for metrics where host-level granularity is not necessary. Learn more about Metrics without Limits™.
Note: The exclusion of tags with ! is not accepted with this feature.
Submit your COUNT type metrics from one of the following sources:
Submission SourceSubmission Method (python)Submission TypeDatadog In-App TypeAgent checkself.count(...)COUNTCOUNTAgent checkself.monotonic_count(...)COUNTCOUNTAPIapi.Metric.send(type="count", ...)COUNTCOUNTDogStatsDdog.count(...)COUNTRATEDogStatsDdog.increment(...)COUNTRATEDogStatsDdog.decrement(...)COUNTRATENote: When submitting a COUNT metric type through DogStatsD, the metric appears as a RATE in-app to ensure relevant comparison across different Agents. Consequently, StatsD counts may appear with a decimal value within Datadog (since they are normalized over a time interval to report units per second).
Submit your RATE type metrics from one of the following sources:
Submission SourceSubmission Method (python)Submission TypeDatadog In-App TypeAgent checkself.rate(...)RATEGAUGEAPIapi.Metric.send(type="rate", ...)RATERATENote: When submitting a RATE metric type through DogStatsD, the metric appears as a GAUGE in-app to ensure relevant comparison across different Agents.
Submit your GAUGE type metrics from one of the following sources:
Submission SourceSubmission Method (Python)Submission TypeDatadog In-App TypeAgent checkself.gauge(...)GAUGEGAUGEAPIapi.Metric.send(type="gauge", ...)GAUGEGAUGEDogStatsDdog.gauge(...)GAUGEGAUGESubmit your HISTOGRAM type metrics from one of the following sources:
Submission SourceSubmission Method (Python)Submission TypeDatadog In-App TypesAgent checkself.histogram(...)HISTOGRAMGAUGE, RATEDogStatsDdog.histogram(...)HISTOGRAMGAUGE, RATESubmitting a TIMER metric to the Datadog Agent is equivalent to submitting a HISTOGRAM metric type within DogStatsD (not to be confused with timers in the standard StatsD). DogStatsD TIMER represents duration data only. For example, the amount of time a section of code takes to execute or how long it takes to fully render a page.
Submit your DISTRIBUTION type metrics from the following source:
Submission SourceSubmission Method (Python)Submission TypeDatadog In-App TypesDogStatsDdog.distribution(...)DISTRIBUTIONGAUGE, COUNTBelow is a summary of all available metric submission sources and methods. This table shows the mapping between the corresponding metric submission type and the in-app types: