Distributions are a metric type that aggregate values sent from multiple hosts during a flush interval to measure statistical distributions across your entire infrastructure.

Global distributions are designed to instrument logical objects, like services, independently from the underlying hosts. Unlike histograms which aggregate on the Agent-side, global distributions send all raw data collected during the flush interval and the aggregation occurs server-side. Because the underlying data structure has not been aggregated and represents raw data, distributions provide two major features:

  • Calculation of percentile aggregations: Percentile aggregations (p50, p75, p90, p95, p99) are calculated from the raw data across all hosts, and are therefore globally accurate.

  • Customization of tagging: This functionality allows you to control the tagging scheme for custom metrics for which host-level granularity is not necessary (for example, transactions per second for a checkout service).

See the Developer Tools section for more implementation details.

Note: Because distributions are a new metric type, they should be instrumented under new metric names during submission to Datadog.


Like other metric types, such as gauges or histograms, distributions have the following aggregations available: count, min, max, sum, and avg. Distributions are initially tagged the same way as other metrics (with custom tags set in code) and are resolved to any host tag based on the host that reported the metric. You can also calculate percentile aggregations for all queryable tags on your distribution, specified on the Metrics Summary page. This provides aggregations for p50, p75, p90, p95, and p99.

Enable Percentiles

After electing to apply percentile aggregations on a distribution metric, these aggregations are automatically available in the graphing UI:

Customize tagging

Distributions provide functionality that allows you to control the tagging for custom metrics where host-level granularity does not make sense. Tag configurations are allowlists of the tags you’d like to keep.

To customize tagging:

  1. Click on your custom distribution metric name in the Metrics Summary table to open the metrics details sidepanel.
  2. Click the Manage Tags button to open the tag configuration modal.
  3. Click the Custom… tab to customize the tags you’d like to keep available for query.

Note: The exclusion of tags is not supported in the allowlist-based customization of tags. Adding tags starting with ! is not accepted.

Audit events

Any tag configuration or percentile aggregation changes create an event in the event stream. This event explains the change and displays the user that made the change.

If you created, updated, or removed a tag configuration on a distribution metric, you can see examples with the following event search:


If you added or removed percentile aggregations to a distribution metric, you can see examples with the following event search:


Further reading

Additional helpful documentation, links, and articles: