From 157a1328fd208fc88ca671ac9ce8e25a5e6fc509 Mon Sep 17 00:00:00 2001 From: Eva Parish Date: Tue, 7 Apr 2026 14:41:02 -0400 Subject: [PATCH 1/3] Fix rollup enforce wording, clarify distribution histogram types --- content/en/dashboards/functions/rollup.md | 14 +++++++------- content/en/dashboards/widgets/distribution.md | 19 ++++++++++++++----- 2 files changed, 21 insertions(+), 12 deletions(-) diff --git a/content/en/dashboards/functions/rollup.md b/content/en/dashboards/functions/rollup.md index 4891fda2159..f14e223aabe 100644 --- a/content/en/dashboards/functions/rollup.md +++ b/content/en/dashboards/functions/rollup.md @@ -1,6 +1,6 @@ --- title: Rollup -description: Control time aggregation and data point intervals using custom rollup functions and moving rollups for metrics. +description: Control time aggregation and datapoint intervals using custom rollup functions and moving rollups for metrics. aliases: - /graphing/functions/rollup/ further_reading: @@ -12,7 +12,7 @@ further_reading: Every metric query is inherently aggregated. However, appending the `.rollup()` function at the end of a query allows you to perform custom [time aggregation][1] that overrides the defaults. This function enables you to define: * The rollup ``: the interval of time your data is aggregated over ([if larger than the query-enforced rollup interval](#rollup-interval-enforced-vs-custom)). -* The rollup ``: How your data points are aggregated within a given rollup time interval. +* The rollup ``: How your datapoints are aggregated within a given rollup time interval. To apply a rollup, navigate to the **Add function** (Σ) button of the graphing editor: @@ -24,8 +24,8 @@ The function takes two parameters, `` and optionally ``: ` | Parameter | Description | |------------|-----------------------------------------------------------------------------------------------------------------| -| `` | Can be `avg`, `sum`, `min`, `max`, or `count`, and defines how data points are aggregated within a given time interval. [Enforced default](#rollup-interval-enforced-vs-custom): `avg`. | -| `` | Time (in seconds) of the interval between two data points displayed. Optional. | +| `` | Can be `avg`, `sum`, `min`, `max`, or `count`, and defines how datapoints are aggregated within a given time interval. [Enforced default](#rollup-interval-enforced-vs-custom): `avg`. | +| `` | Time (in seconds) of the interval between two datapoints displayed. Optional. | You can use them individually or together, for instance `.rollup(sum,120)`. The following bar graph displays a week's worth of CPU usage for a host **without** using the `.rollup()` function: @@ -43,13 +43,13 @@ The following bar graph displays the same metric, graphed using a day-long rollu | `moving_rollup` | Rollup to combine the points in the last X seconds. | `moving_rollup(, , )` | -Applying the `moving_rollup()` function to a query allows you to combine points from the most recent specified time range—that is, the last X seconds. Like with `.rollup()`, `` can be `sum`/`min`/`max`/`count`/`avg` and defines how data points are aggregated within the given time interval. +Applying the `moving_rollup()` function to a query allows you to combine points from the most recent specified time range—that is, the last X seconds. Like with `.rollup()`, `` can be `sum`/`min`/`max`/`count`/`avg` and defines how datapoints are aggregated within the given time interval. ## Rollup interval: enforced vs custom When graphing, Datadog sets a limit on the number of points per timeseries. To retain visual clarity, a series can have up to 1500 points. To respect this limit, Datadog rolls up datapoints automatically, defaulting to the `avg` method, effectively displaying the average of all datapoints within a time interval for a given metric. The default rollup time interval varies depending on how the data is visualized. See the following chart to reference these default time intervals: -| Timeframe | Rollup Interval, Line Graph | Rollup Interval, Bar Graph | Rollup Interval, API | +| Time frame | Rollup Interval, Line Graph | Rollup Interval, Bar Graph | Rollup Interval, API | |---------------------|-----------------------------|----------------------------|----------------------| | The past hour | 20s | 1m | 20s | | The past four hours | 1m | 2m | 1m | @@ -58,7 +58,7 @@ When graphing, Datadog sets a limit on the number of points per timeseries. To r | The past week | 1hr | 2hr | 1hr | | The past month | 4hr | 12hr | 4hr | -A custom `.rollup()` function can be used to enforce the type of time aggregation applied (`avg`, `min`, `max`, `count`, or `sum`) and optionally the time interval to rollup. Using this function, you can set the rollup time interval to a different value than the defaults, up to a limit of 1500 points. This supports up to one point per minute over a day. +A custom `.rollup()` function can be used to specify the type of time aggregation applied (`avg`, `min`, `max`, `count`, or `sum`) and optionally the time interval to rollup. Using this function, you can set the rollup time interval to a different value than the defaults, up to a limit of 1500 points. This supports up to one point per minute over a day. **Note**: Queries for `COUNT` and `RATE` type metrics have the `.as_count()` modifier appended automatically in the UI, which sets the rollup method used to `sum` and disables interpolation. This `.as_count()` is explicitly visible at the end of the query: diff --git a/content/en/dashboards/widgets/distribution.md b/content/en/dashboards/widgets/distribution.md index 497aa318573..374fa8c3bc9 100644 --- a/content/en/dashboards/widgets/distribution.md +++ b/content/en/dashboards/widgets/distribution.md @@ -22,7 +22,7 @@ further_reading: text: "Querying" --- -The Distribution visualization shows data aggregated across one or several tags, such as *hosts*. Unlike the [heatmap][1], a distribution graph's x-axis is quantity rather than time. +The Distribution visualization shows data aggregated across one or several tags, such as *hosts*. Unlike the [heat map][1], a distribution graph's x-axis is quantity rather than time. This visualization displays only a single query; additional queries are disregarded. @@ -34,20 +34,29 @@ This visualization displays only a single query; additional queries are disregar ### Configuration -1. Choose the data to graph.The Distribution visualization supports metrics, live processes, APM request latency, log events, and RUM events. -**Note**: This visualization type is useful only when data is aggregated across tag keys, such as for each `host`. -1. Make a selection in the "`avg`/`max`/`min`/`sum by`/" control to see your data across the associated tags. +1. Choose the data to graph. The Distribution visualization supports metrics, live processes, APM request latency, log events, and RUM events. + **Note**: This visualization type is useful only when data is aggregated across tag keys, such as for each `host`. +1. Make a selection in the `avg`/`last`/`max`/`min`/`sum` control to see your data across the associated tags. 1. Customize your graph with the available options. ### Options +#### Histogram of points vs. histogram of groups + +The Distribution widget supports two histogram types: + +- **Histogram of points**: Each individual datapoint (for example, a raw request latency measurement) contributes to a bucket based on its value. Use this when you want to see the full distribution of measurements across all recordings. +- **Histogram of groups**: Each group (such as a service or host) is first reduced to a single aggregated value (for example, the p75 latency), and then those aggregated values are distributed across buckets. The resulting shape reflects the spread of per-group summary values, not individual measurements. + +**Note**: Because these two types aggregate data differently, switching between them can significantly change the shape of the histogram. + #### Percentile markers With APM request distributions, you can add percentile markers on the x-axis. {{< img src="dashboards/widgets/options/distribution_marker_controls.jpg" alt="Marker control preferences" style="width:80%;">}} -#### X-axis and Y-axis controls +#### X-axis and y-axis controls Axis controls are available through the UI and the JSON editor. From 5eb826f94f33beff1a2c745eae105657c0d48495 Mon Sep 17 00:00:00 2001 From: Eva Parish Date: Wed, 8 Apr 2026 12:29:05 -0400 Subject: [PATCH 2/3] Revise with review feedback --- content/en/dashboards/widgets/distribution.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/en/dashboards/widgets/distribution.md b/content/en/dashboards/widgets/distribution.md index 374fa8c3bc9..0e4a609ef78 100644 --- a/content/en/dashboards/widgets/distribution.md +++ b/content/en/dashboards/widgets/distribution.md @@ -34,8 +34,7 @@ This visualization displays only a single query; additional queries are disregar ### Configuration -1. Choose the data to graph. The Distribution visualization supports metrics, live processes, APM request latency, log events, and RUM events. - **Note**: This visualization type is useful only when data is aggregated across tag keys, such as for each `host`. +1. Choose the data to graph. The Distribution visualization supports many sources, including metrics, live processes, APM request latency, log events, and RUM events. 1. Make a selection in the `avg`/`last`/`max`/`min`/`sum` control to see your data across the associated tags. 1. Customize your graph with the available options. @@ -43,12 +42,12 @@ This visualization displays only a single query; additional queries are disregar #### Histogram of points vs. histogram of groups -The Distribution widget supports two histogram types: +The Distribution widget supports these histogram types: - **Histogram of points**: Each individual datapoint (for example, a raw request latency measurement) contributes to a bucket based on its value. Use this when you want to see the full distribution of measurements across all recordings. - **Histogram of groups**: Each group (such as a service or host) is first reduced to a single aggregated value (for example, the p75 latency), and then those aggregated values are distributed across buckets. The resulting shape reflects the spread of per-group summary values, not individual measurements. -**Note**: Because these two types aggregate data differently, switching between them can significantly change the shape of the histogram. +
Because these two types aggregate data differently, switching between them can significantly change the shape of the histogram.
#### Percentile markers From 8b431decc5dffbe3e75cdc2d5f4d6fe0b2c762ca Mon Sep 17 00:00:00 2001 From: Eva Parish Date: Wed, 8 Apr 2026 13:06:45 -0400 Subject: [PATCH 3/3] Heatmap back to one word --- content/en/dashboards/widgets/distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/dashboards/widgets/distribution.md b/content/en/dashboards/widgets/distribution.md index 0e4a609ef78..fe3dab3db57 100644 --- a/content/en/dashboards/widgets/distribution.md +++ b/content/en/dashboards/widgets/distribution.md @@ -22,7 +22,7 @@ further_reading: text: "Querying" --- -The Distribution visualization shows data aggregated across one or several tags, such as *hosts*. Unlike the [heat map][1], a distribution graph's x-axis is quantity rather than time. +The Distribution visualization shows data aggregated across one or several tags, such as *hosts*. Unlike the [heatmap][1], a distribution graph's x-axis is quantity rather than time. This visualization displays only a single query; additional queries are disregarded.