Skip to content

Add OTel Histogram support documentation #37526

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shanelhuang wants to merge 1 commit into
base: master
Choose a base branch
from
+27 −23
Open

Add OTel Histogram support documentation #37526

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 19 additions & 13 deletions content/en/metrics/open_telemetry/otlp_metric_types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:

@domalessi domalessi Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The default mapping for both histogram temporality types is as follows:
The default mapping for both 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.

@domalessi domalessi Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **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.
- **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.

@domalessi domalessi Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**Note**: See [Producing Delta Temporality Metrics with OpenTelemetry][3] for configuration instructions.
**Note**: See [Producing Delta Temporality Metrics with OpenTelemetry][3] for instructions on configuring your SDK or Collector to emit delta temporality.


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.

@domalessi domalessi Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first sentence repeats what the Delta bullet already states ("ingested natively... The original bucket structure is preserved").

Suggested change
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.
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:

`<METRIC_NAME>.bucket`, tagged by `lower_bound` and `upper_bound`
Expand All @@ -96,14 +102,14 @@ The Datadog Agent and the OpenTelemetry Collector Datadog exporter allow changin
**Datadog In-App Type**: COUNT

`<METRIC_NAME>.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. <br>
: 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. <br>
**Datadog In-App Type**: GAUGE

`<METRIC_NAME>.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.<br>
: 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.<br>
**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
Comment on lines 114 to 115

@domalessi domalessi Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[1]: /metrics/distributions
[2]: /dashboards/functions/arithmetic/#cumulative-sum

Expand Down Expand Up @@ -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.

Expand Down
3 changes: 2 additions & 1 deletion content/en/metrics/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

@domalessi domalessi Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- (Exponential, Explicit) HISTOGRAM
- HISTOGRAM (Explicit, Exponential)


**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.

Expand Down
15 changes: 6 additions & 9 deletions content/en/opentelemetry/guide/otlp_histogram_heatmaps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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].
Expand All @@ -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" %}}
Expand All @@ -71,7 +68,7 @@ otlp_config:

### Heatmap widget configuration

The [heatmap widget][5] uses the set of `<YOUR METRIC NAME>.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 `<YOUR METRIC NAME>.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 `<YOUR METRIC NAME>.bucket` as the metric to visualize.
2. Choose the `pre-binned data` option on the `distributions of` menu.
Expand Down
Loading