Add OTel Histogram support documentation#37526
Open
shanelhuang wants to merge 1 commit into
Open
Conversation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
Preview links (active after the
|
domalessi
reviewed
Jun 15, 2026
domalessi
left a comment
domalessi
left a comment
Contributor
There was a problem hiding this comment.
Thanks for the edits! A few suggestions in line! Tag me or re-request review when ready for another look.
| **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. |
Contributor
There was a problem hiding this comment.
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 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: |
Contributor
There was a problem hiding this comment.
Suggested change
| The default mapping for both histogram temporality types is as follows: | |
| The default mapping for both temporality types is as follows: |
| 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. |
Contributor
There was a problem hiding this comment.
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. |
Contributor
There was a problem hiding this comment.
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. |
| - RATE | ||
| - GAUGE | ||
| - DISTRIBUTION | ||
| - (Exponential, Explicit) HISTOGRAM |
Contributor
There was a problem hiding this comment.
Suggested change
| - (Exponential, Explicit) HISTOGRAM | |
| - HISTOGRAM (Explicit, Exponential) |
Comment on lines
114
to
115
| [1]: /metrics/distributions | ||
| [2]: /dashboards/functions/arithmetic/#cumulative-sum |
Contributor
There was a problem hiding this comment.
Suggested change
| [1]: /metrics/distributions | |
| [2]: /dashboards/functions/arithmetic/#cumulative-sum |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do? What is the motivation?
Updates documentation to add support for OTel Histograms (Explicit Bucket and Exponential), reflecting that these are now stored natively in Datadog as true distributions.
content/en/metrics/types.md: Updated in-app metric types list from four to five types, adding(Exponential, Explicit) HISTOGRAMcontent/en/metrics/open_telemetry/otlp_metric_types.md(shared with OTel reference page): Updated Histogram tab to describe both Explicit Bucket and Exponential Histogram types; updated default mapping to reflect native ingestion without DDSketch conversion; replaced "Datadog exporter" with "OTLP Exporter" throughoutcontent/en/opentelemetry/guide/otlp_histogram_heatmaps.md: Removed outdated note about Exponential Histograms being converted to distributions; removedcountersmode from OTLP Exporter tab; replaced "Datadog Exporter" with "OTLP Exporter" throughoutMerge instructions
Merge readiness:
Additional notes