From 21816fbab8e33d8374c7b0aaf6fbaa572362660a Mon Sep 17 00:00:00 2001 From: Shanel Huang Date: Mon, 15 Jun 2026 17:02:37 -0400 Subject: [PATCH] Add OTel Histogram (Explicit/Exponential) support to metrics docs Co-Authored-By: Claude Sonnet 4.6 --- .../open_telemetry/otlp_metric_types.md | 32 +++++++++++-------- content/en/metrics/types.md | 3 +- .../guide/otlp_histogram_heatmaps.md | 15 ++++----- 3 files changed, 27 insertions(+), 23 deletions(-) diff --git a/content/en/metrics/open_telemetry/otlp_metric_types.md b/content/en/metrics/open_telemetry/otlp_metric_types.md index 1515217e74d..9b62d1862b7 100644 --- a/content/en/metrics/open_telemetry/otlp_metric_types.md +++ b/content/en/metrics/open_telemetry/otlp_metric_types.md @@ -17,9 +17,9 @@ aliases: ## Overview -The Datadog Agent and the OpenTelemetry Collector Datadog exporter can ingest metrics in the OpenTelemetry format (OTLP), which can be produced by OpenTelemetry-instrumented applications. +The Datadog Agent and the OpenTelemetry Collector OTLP Exporter can ingest metrics in the OpenTelemetry format (OTLP), which can be produced by OpenTelemetry-instrumented applications. -The following OTLP metric types can be ingested by the Datadog Agent and the OpenTelemetry Collector Datadog exporter: +The following OTLP metric types can be ingested by the Datadog Agent and the OpenTelemetry Collector OTLP Exporter: - Sums - Gauges - Histograms @@ -66,19 +66,25 @@ OTLP Gauges are mapped to Datadog Gauges, since they do not provide an aggregati {{% /tab %}} {{% tab "Histogram" %}} -An OTLP Histogram represents the statistical distribution of a set of values on a given time window, by storing certain aggregation metrics such as the population sum or count together with a series of bucket counts. Histograms have one feature that influences the mapping: +OTLP defines two histogram types for representing value distributions: + +- **Histogram (Explicit Bucket)**: Uses fixed, user-defined or SDK-default bucket boundaries. Each bucket counts how many measured values fall within its bounds. Also stores sum, count, and optional min/max. +- **ExponentialHistogram**: Uses dynamically computed bucket boundaries based on a scale parameter (base = 2^(2^(-scale))), which allows high dynamic range with small relative error. Datadog supports scales in the range [-4, 8]. + +Both types have one feature that influences the mapping: - *Aggregation temporality*, which can be cumulative or delta. Delta metrics have no overlap in their time windows, while cumulative metrics represent a time window from a fixed start point in time. -The default mapping is as follows: -1. Delta histograms are reported as Datadog distributions. [Read more about distributions][1] to understand the available aggregations. Histograms with a count of 0 are dropped. -2. For cumulative histograms, the delta between consecutive points is calculated and reported to Datadog as a distribution. Deltas with a count of 0 are not reported. You may use the [`cumsum` arithmetic function][2] on individual aggregations to recover the value in the OTLP payload. +The default mapping for both histogram temporality types is as follows: + +- **Delta (Default and Recommended)**: Explicit Bucket and Exponential Histograms are ingested natively and reported as Datadog distributions. The original bucket structure is preserved — no conversion to DDSketch occurs. Histograms with a count of 0 are dropped. +- **Cumulative**: The delta between consecutive points is calculated and reported to Datadog as a distribution. Deltas with a count of 0 are not reported. -**Note**: Histogram metrics in OTLP are mapped by default to Distribution metrics. Because of how OTLP sends this data, percentile aggregations and the max and min (if not available on the original OTLP data) are approximations, not accurate calculations. +**Note**: See [Producing Delta Temporality Metrics with OpenTelemetry][3] for configuration instructions. -Datadog distributions are powered by the [DDSketch data structure][4]. See [Distributions][5] for details on enabling percentile aggregations and threshold queries on your mapped metrics. +Explicit and Exponential Histograms are stored natively in Datadog, preserving the original bucket boundaries and counts. Percentile aggregations are computed directly from the native bucket structure. Min and max are stored when provided; if not present in the original data, they are derived from the bucket boundaries. -The Datadog Agent and the OpenTelemetry Collector Datadog exporter allow changing the Histogram export in the `histogram` subsection. +The Datadog Agent and the OpenTelemetry Collector OTLP Exporter allow changing the Histogram export in the `histogram` subsection. - If the `mode` is set to `counters`, the following metrics are produced: `.bucket`, tagged by `lower_bound` and `upper_bound` @@ -96,14 +102,14 @@ The Datadog Agent and the OpenTelemetry Collector Datadog exporter allow changin **Datadog In-App Type**: COUNT `.min` -: Minimum of values submitted during the time window. Only available for delta OTLP Histograms. Available since: Datadog exporter v0.75.0 and Datadog Agent v6.45.0 and v7.45.0.
+: Minimum of values submitted during the time window. Only available for delta OTLP Histograms. Available since: OTLP Exporter v0.75.0 and Datadog Agent v6.45.0 and v7.45.0.
**Datadog In-App Type**: GAUGE `.max` -: Maximum of values submitted during the time window. Only available for delta OTLP Histograms. Available since: Datadog exporter v0.75.0 and Datadog Agent v6.45.0 and v7.45.0.
+: Maximum of values submitted during the time window. Only available for delta OTLP Histograms. Available since: OTLP Exporter v0.75.0 and Datadog Agent v6.45.0 and v7.45.0.
**Datadog In-App Type**: GAUGE -**Note**: `send_aggregation_metrics` is useful only when not using the distributions mode. Before the Datadog exporter v0.75.0 and the Datadog Agent v6.45.0 and v7.45.0 use `send_count_sum_metrics` instead. +**Note**: `send_aggregation_metrics` is useful only when not using the distributions mode. Before the OTLP Exporter v0.75.0 and the Datadog Agent v6.45.0 and v7.45.0 use `send_count_sum_metrics` instead. [1]: /metrics/distributions [2]: /dashboards/functions/arithmetic/#cumulative-sum @@ -131,7 +137,7 @@ An OTLP Summary is a legacy type that conveys quantile information about a popul OTLP supports two kinds of attributes: datapoint-level attributes and resource attributes. These attributes may follow OpenTelemetry semantic conventions and have well-known semantics. -The Datadog Agent and the OpenTelemetry Collector Datadog exporter map the datapoints-level attributes as tags. Resource attributes following OpenTelemetry semantic conventions are mapped to the equivalent Datadog conventions if they exist. +The Datadog Agent and the OpenTelemetry Collector OTLP Exporter map the datapoints-level attributes as tags. Resource attributes following OpenTelemetry semantic conventions are mapped to the equivalent Datadog conventions if they exist. You may add all resource attributes as tags by using the `resource_attributes_as_tags` flag. diff --git a/content/en/metrics/types.md b/content/en/metrics/types.md index ef4d6fea3f0..1509ef5764f 100644 --- a/content/en/metrics/types.md +++ b/content/en/metrics/types.md @@ -40,12 +40,13 @@ The following metric submission types are accepted: - [HISTOGRAM](?tab=histogram#metric-types) - [DISTRIBUTION](?tab=distribution#metric-types) -These different metric submission types are mapped to four in-app metric types found within the Datadog web application: +These different metric submission types are mapped to five in-app metric types found within the Datadog web application: - COUNT - RATE - GAUGE - DISTRIBUTION +- (Exponential, Explicit) HISTOGRAM **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. diff --git a/content/en/opentelemetry/guide/otlp_histogram_heatmaps.md b/content/en/opentelemetry/guide/otlp_histogram_heatmaps.md index 761c804a472..7fe931f80fb 100644 --- a/content/en/opentelemetry/guide/otlp_histogram_heatmaps.md +++ b/content/en/opentelemetry/guide/otlp_histogram_heatmaps.md @@ -15,8 +15,6 @@ The OpenTelemetry Protocol (OTLP) supports sending OTLP Histograms, a type of me You can visualize this datatype as a [heatmap][5] in Datadog by following the steps on this page. -**Note**: The related OTLP Exponential Histogram type can also be displayed as a heatmap, since it is converted to a distribution. Read more about distributions on the [dedicated Distributions page][4]. - ## Setup This guide assumes you already have a [functioning setup for sending OpenTelemetry metrics to Datadog][1]. @@ -30,25 +28,24 @@ If you are producing metrics from an OpenTelemetry SDK, take the following steps For metrics coming from other sources, ensure if possible that these come as delta OTLP Histograms with the minimum and maximum fields set. -### Datadog Exporter or Datadog Agent configuration +### OTLP Exporter or Datadog Agent configuration -Set the histogram mode and enable aggregation metrics on your Datadog Exporter or Datadog Agent. +Set the histogram mode and enable aggregation metrics on your OTLP Exporter or Datadog Agent. {{< tabs >}} -{{% tab "Datadog Exporter (OpenTelemetry Collector)" %}} +{{% tab "OTLP Exporter (OpenTelemetry Collector)" %}} -In the `collector.yaml` file for the Datadog Exporter, configure the histogram mode to `counters` and enable aggregation metrics with the `send_aggregation_metrics` flag. +In the `collector.yaml` file for the OTLP Exporter, enable aggregation metrics with the `send_aggregation_metrics` flag. ```yaml exporters: datadog: metrics: histograms: - mode: counters send_aggregation_metrics: true ``` -**Note**: `send_aggregation_metrics` is available starting with Datadog Exporter v0.75.0. If you are using an earlier version, use the `send_count_sum_metrics` flag instead. The minimum and maximum are missing in earlier versions. +**Note**: `send_aggregation_metrics` is available starting with OTLP Exporter v0.75.0. If you are using an earlier version, use the `send_count_sum_metrics` flag instead. The minimum and maximum are missing in earlier versions. {{% /tab %}} {{% tab "Datadog Agent" %}} @@ -71,7 +68,7 @@ otlp_config: ### Heatmap widget configuration -The [heatmap widget][5] uses the set of `.bucket` metrics generated by the Datadog Exporter or Datadog Agent, each corresponding to a different histogram bucket. To visualize your histogram as a heatmap: +The [heatmap widget][5] uses the set of `.bucket` metrics generated by the OTLP Exporter or Datadog Agent, each corresponding to a different histogram bucket. To visualize your histogram as a heatmap: 1. Select `.bucket` as the metric to visualize. 2. Choose the `pre-binned data` option on the `distributions of` menu.