Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(metrics): sharper histogram percentiles across bucket layouts (#122465)

Daniel Visca36806304df62
diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json
index aacfa5ab9060..56b796b75b9e 100644
--- a/frontend/src/queries/schema.json
+++ b/frontend/src/queries/schema.json
@@ -39276,6 +39276,13 @@
"description": "Clause alias that produced this series (`formula` for the formula result)",
"type": "string"
},
+ "histogramBounds": {
+ "description": "Bucket upper edges a histogram quantile series was estimated from. The true quantile can be anywhere between two edges.",
+ "items": {
+ "type": "number"
+ },
+ "type": "array"
+ },
"labels": {
"additionalProperties": {
"type": "string"
diff --git a/frontend/src/queries/schema/schema-general.ts b/frontend/src/queries/schema/schema-general.ts
index 818b42eca737..37ed2c5a0405 100644
--- a/frontend/src/queries/schema/schema-general.ts
+++ b/frontend/src/queries/schema/schema-general.ts
@@ -5011,6 +5011,8 @@ export interface MetricsQuerySeries {
clause?: string
/** UCUM unit of the returned values, e.g. "By", "ms", "1/s". It is the ingested unit, except that a count of series has no unit and a rate is per second. Empty when the values have no unit. */
unit?: string
+ /** Bucket upper edges a histogram quantile series was estimated from. The true quantile can be anywhere between two edges. */
+ histogramBounds?: number[]
}
export interface MetricsQueryResponse extends AnalyticsQueryResponseBase {
diff --git a/posthog/schema.py b/posthog/schema.py
index 994d7f74ea88..8155ffb5f9a0 100644
--- a/posthog/schema.py
+++ b/posthog/schema.py
@@ -2718,6 +2718,13 @@ class MetricsQuerySeries(BaseModel):
default=None,
description=("Clause alias that produced this series (`formula` for the formula result)"),
)
+ histogramBounds: list[float] | None = Field(
+ default=None,
+ description=(
+ "Bucket upper edges a histogram quantile series was estimated from. The"
+ " true quantile can be anywhere between two edges."
+ ),
+ )
labels: dict[str, str] = Field(
...,
description=("Label values identifying this series; empty for an ungrouped query"),
diff --git a/products/metrics/backend/facade/api.py b/products/metrics/backend/facade/api.py
index c17d2994d358..cda08645418b 100644
--- a/products/metrics/backend/facade/api.py
+++ b/products/metrics/backend/facade/api.py
@@ -184,10 +184,13 @@ def _assemble_series(
their labels match: two physical series can share a label-set."""
by_labels: dict[tuple[tuple[tuple[str, str], ...], int | None], dict[str, float | None]] = {}
fingerprints_by_labels: dict[tuple[tuple[tuple[str, str], ...], int | None], set[int]] = {}
+ bounds_by_labels: dict[tuple[tuple[tuple[str, str], ...], int | None], set[float]] = {}
for row in rows:
key = (tuple(sorted(row["labels"].items())), row.get("series_key"))
by_labels.setdefault(key, {})[row["time"]] = row["value"]
fingerprints_by_labels.setdefault(key, set()).update(row["series_fingerprints"])
+ if "histogram_bounds" in row:
+ bounds_by_labels.setdefault(key, set()).update(row["histogram_bounds"])
# Rank and truncate on the sparse values BEFORE zero-filling, so a
# high-cardinality group-by never materializes label_sets x grid points
@@ -203,6 +206,7 @@ def _assemble_series(
metric_name=clause.metric_name,
clause=clause.name,
unit=_output_unit(_unit_for_fingerprints(fingerprints_by_labels[key], units_by_fingerprint), clause),
+ histogram_bounds=tuple(sorted(bounds_by_labels[key])) if key in bounds_by_labels else None,
)
for key, values in ranked[:MAX_SERIES_PER_CLAUSE]
]
diff --git a/products/metrics/backend/facade/contracts.py b/products/metrics/backend/facade/contracts.py
index b3f4a2cdf55c..c311023d3cca 100644
--- a/products/metrics/backend/facade/contracts.py
+++ b/products/metrics/backend/facade/contracts.py
@@ -176,6 +176,9 @@ class MetricSeries:
# from the ingested unit when the clause transforms the values: COUNT has no
# unit and RATE is per second. Set by `run_metric_query`, not by callers.
unit: str | None = None
+ # Bucket upper edges a histogram quantile was estimated from, merged over every
+ # point. The estimate can be anywhere between two edges. None for other aggregations.
+ histogram_bounds: tuple[float, ...] | None = None
@dataclass(frozen=True, slots=True)
diff --git a/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py b/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py
index a326a044dc31..c4a66d368476 100644
--- a/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py
+++ b/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py
@@ -6,6 +6,7 @@ the response into the grid the heatmap panel draws: one column per time bucket,
upper bound, cell = observation count.
"""
+import math
import datetime as dt
from datetime import datetime
from typing import TYPE_CHECKING, Optional, cast
@@ -61,6 +62,20 @@ def _grid_time_key(value: datetime) -> str:
return value.strftime("%Y-%m-%d %H:%M:%S")
+def _round_keeping_total(values: list[float]) -> list[int]:
+ """Round merged counts to whole observations without losing any.
+
+ Merging splits a bucket over finer edges, so one observation can become four quarters. Rounding
+ each alone would drop it; the largest remainders take the observations that rounding down loses.
+ """
+ floors = [math.floor(value) for value in values]
+ missing = round(sum(values)) - sum(floors)
+ by_remainder = sorted(range(len(values)), key=lambda index: floors[index] - values[index])
+ for index in by_remainder[:missing]:
+ floors[index] += 1
+ return floors
+
+
class MetricsHistogramQueryRunner(AnalyticsQueryRunner[MetricsHistogramQueryResponse]):
query: MetricsHistogramQuery
cached_response: CachedMetricsHistogramQueryResponse
@@ -164,15 +179,9 @@ class MetricsHistogramQueryRunner(AnalyticsQueryRunner[MetricsHistogramQueryResp
# The runner may coarsen the interval to stay within its bucket limit, so read its step.
step = _interval_step(runner.interval)
- # Rows: (time, bounds, bounds_variants, counts). Bounds variants must agree (same rule
- # as the quantile runner) or the grid has no stable y axis.
- distinct_bounds = {tuple(variant) for row in response.results for variant in row[2] if variant}
- if len(distinct_bounds) > 1:
- raise ExposedHogQLError(
- "histogram bounds differ across the selected time range; "
- "narrow the query with filters so all series share one bucket layout"
- )
- bounds = sorted(distinct_bounds)[0] if distinct_bounds else []
+ # Series can use different bucket layouts, so every time bucket merges onto the union of
+ # the edges. The grid then has one stable y axis.
+ bounds = runner.histogram_edges(response.results)
# Assemble the grid: column per time bucket, row per bound, zero-filled.
# `runner.date_to` is exclusive, so the last column is the bucket whose
@@ -191,10 +200,11 @@ class MetricsHistogramQueryRunner(AnalyticsQueryRunner[MetricsHistogramQueryResp
f"heatmap grid would hold {len(bounds)} rows x {len(grid_times)} columns; "
"use a coarser interval, a narrower range, or fewer histogram bounds"
)
+ # Merge only after the size check: every merged time bucket holds the whole union of edges.
+ distributions = runner.merged_distributions(response.results, edges=bounds)
counts = [[0 for _ in grid_times] for _ in bounds]
- for row in response.results:
- time_val = row[0]
+ for (time_val, *_), merged in distributions.items():
if isinstance(time_val, datetime):
time_key = _grid_time_key(time_val.astimezone(grid_start.tzinfo))
else:
@@ -203,11 +213,8 @@ class MetricsHistogramQueryRunner(AnalyticsQueryRunner[MetricsHistogramQueryResp
column = time_index.get(time_key)
if column is None:
continue
- row_bounds = list(row[1])
- row_counts = list(row[3])
- for bound_idx, bound in enumerate(row_bounds):
- if bound_idx < len(bounds) and bounds[bound_idx] == bound and bound_idx < len(row_counts):
- counts[bound_idx][column] += int(row_counts[bound_idx])
+ for bound_idx, count in enumerate(_round_keeping_total(merged.counts[: len(bounds)])):
+ counts[bound_idx][column] += count
# The base response requires `results`; the heatmap grid lives in times/bounds/counts,
# so `results` is returned as null.
diff --git a/products/metrics/backend/hogql_queries/metrics_query_runner.py b/products/metrics/backend/hogql_queries/metrics_query_runner.py
index cd271a85355e..328767b3b816 100644
--- a/products/metrics/backend/hogql_queries/metrics_query_runner.py
+++ b/products/metrics/backend/hogql_queries/metrics_query_runner.py
@@ -266,6 +266,7 @@ class MetricsQueryRunner(AnalyticsQueryRunner[MetricsQueryResponse]):
metricName=s.metric_name,
clause=s.clause,
unit=s.unit or None,
+ histogramBounds=list(s.histogram_bounds) if s.histogram_bounds is not None else None,
)
for s in series
]
diff --git a/products/metrics/backend/metric_query_runner.py b/products/metrics/backend/metric_query_runner.py
index 801afc94a33a..a6dfd171f28f 100644
--- a/products/metrics/backend/metric_query_runner.py
+++ b/products/metrics/backend/metric_query_runner.py
@@ -7,9 +7,10 @@ Filters use fingerprints, and group-by joins labels after reduction.
import re
import math
+import bisect
import datetime as dt
-from collections.abc import Sequence
-from typing import Any, Literal
+from collections.abc import Iterator, Sequence
+from typing import Any, Literal, NamedTuple
from zoneinfo import ZoneInfo
from posthog.hogql import ast
@@ -19,6 +20,7 @@ from posthog.hogql.parser import parse_expr, parse_select
from posthog.hogql.query import execute_hogql_query
from posthog.clickhouse.client.connection import Workload
+from posthog.dataclasses import frozen
from posthog.models import Team
from products.metrics.backend.facade.contracts import MetricFilter, MetricGroupBy, MetricQueryTooManyRowsError
@@ -154,6 +156,169 @@ def _histogram_quantile(quantile: float, bounds: list[float], counts: list[float
return bounds[-1]
+class MergedDistribution(NamedTuple):
+ bounds: list[float]
+ counts: list[float]
+ # The edges the quantile estimate is accurate to; see `_resolution_edges`.
+ resolution_bounds: list[float]
+ fingerprints: set[int]
+
+
+@frozen
+class _Histogram:
+ bounds: list[float]
+ counts: list[float]
+
+
+@frozen
+class _SourceBucket:
+ lower: float
+ upper: float
+ count: float
+
+
+def _exponential_upper_edges(bounds: list[float], counts: list[Any]) -> tuple[list[float], list[Any]]:
+ """Convert an exponential histogram's stored edges into ascending upper edges for the quantile.
+
+ Ingest stores the zero bucket as 0, then for each negative bucket `[-base**(i+1), -base**i)` its edge
+ nearest zero, then for each positive bucket `(base**i, base**(i+1)]` its lower edge. Consecutive
+ stored edges give `base`. A sign with only one bucket gives no `base`, so that bucket becomes zero-width
+ at its stored edge, which is inside its true range. Empty buckets fill the gaps between ranges.
+
+ A bucket shares its inner edge with its neighbor, so that edge reuses the neighbor's exact stored
+ value instead of recomputing it as `bound * base`: the two can differ in the last bit, which makes
+ the edges stop being sorted. Only the outermost bucket on each side has no neighbor to reuse, so it
+ falls back to the computed edge.
+ """
+ negative = [(bound, count) for bound, count in zip(bounds, counts) if bound < 0]
+ positive = [(bound, count) for bound, count in zip(bounds, counts) if bound > 0]
+ buckets: list[tuple[float, float, Any]] = [(0.0, 0.0, count) for bound, count in zip(bounds, counts) if bound == 0]
+ if negative:
+ base = negative[1][0] / negative[0][0] if len(negative) > 1 else 1.0
+ buckets += [
+ (negative[i + 1][0] if i + 1 < len(negative) else bound * base, bound, count)
+ for i, (bound, count) in enumerate(negative)
+ ]
+ if positive:
+ base = positive[1][0] / positive[0][0] if len(positive) > 1 else 1.0
+ buckets += [
+ (bound, positive[i + 1][0] if i + 1 < len(positive) else bound * base, count)
+ for i, (bound, count) in enumerate(positive)
+ ]
+ buckets.sort(key=lambda bucket: (bucket[1], bucket[0]))
+
+ edges: list[float] = []
+ ascending: list[Any] = []
+ for lower, upper, count in buckets:
+ previous = edges[-1] if edges else min(0.0, upper)
+ if lower != previous:
+ edges.append(lower)
+ ascending.append(0)
+ edges.append(upper)
+ ascending.append(count)
+ return edges, ascending
+
+
+def _source_buckets(bounds: Sequence[float], counts: Sequence[float]) -> Iterator[_SourceBucket]:
+ """Yield the edges and count of each bucket that holds observations.
+
+ Counts past the last edge are the overflow bucket, whose upper edge is infinite. With no edges at
+ all, every observation is in one bucket that is open at both ends.
+ """
+ for index, count in enumerate(counts):
+ if not count:
+ continue
+ if index >= len(bounds):
+ yield _SourceBucket(lower=bounds[-1] if bounds else -math.inf, upper=math.inf, count=count)
+ else:
+ yield _SourceBucket(
+ lower=bounds[index - 1] if index > 0 else min(0.0, bounds[0]), upper=bounds[index], count=count
+ )
+
+
+def _row_distribution(row: Sequence[Any], group_count: int) -> _Histogram:
+ """Bounds and counts for one `_build_histogram_query` row, as ascending upper edges.
+
+ Converts an exponential histogram's stored lower edges to upper edges; other layouts are
+ already upper edges and pass through unchanged.
+ """
+ bounds, counts = list(row[1 + group_count]), list(row[2 + group_count])
+ if row[4 + group_count] == MetricType.EXPONENTIAL_HISTOGRAM.value:
+ bounds, counts = _exponential_upper_edges(bounds, counts)
+ return _Histogram(bounds=bounds, counts=counts)
+
+
+def _merge_histograms(distributions: Sequence[_Histogram]) -> _Histogram:
+ """Merge bucket counts of different layouts onto the union of their edges.
+
+ A source bucket spreads over the union buckets it covers, in proportion to their width, which is the
+ same linear assumption the quantile interpolation makes. A source overflow bucket goes to the next
+ union bucket above its lowest edge, so its quantile stays near that edge as Prometheus reports it.
+ One sweep over the bucket ends keeps the work near-linear in the number of source buckets.
+ """
+ layouts = {tuple(distribution.bounds) for distribution in distributions}
+ if len(layouts) == 1:
+ width = max(len(distribution.counts) for distribution in distributions)
+ merged = [0.0] * width
+ for distribution in distributions:
+ for index, count in enumerate(distribution.counts):
+ merged[index] += count
+ return _Histogram(bounds=list(next(iter(layouts))), counts=merged)
+
+ edges = sorted({bound for layout in layouts for bound in layout})
+ merged = [0.0] * (len(edges) + 1)
+ density_changes: dict[float, float] = {}
+ open_changes: dict[float, int] = {}
+ for distribution in distributions:
+ for bucket in _source_buckets(distribution.bounds, distribution.counts):
+ lower, upper = bucket.lower, bucket.upper
+ if upper == math.inf:
+ merged[bisect.bisect_right(edges, lower)] += bucket.count
+ elif upper <= lower:
+ merged[bisect.bisect_left(edges, upper)] += bucket.count
+ else:
+ density = bucket.count / (upper - lower)
+ density_changes[lower] = density_changes.get(lower, 0.0) + density
+ density_changes[upper] = density_changes.get(upper, 0.0) - density
+ open_changes[lower] = open_changes.get(lower, 0) + 1
+ open_changes[upper] = open_changes.get(upper, 0) - 1
+
+ density = 0.0
+ open_buckets = 0
+ # The union edges split the sweep too, so each segment lies inside one union bucket.
+ positions = sorted({*density_changes, *edges})
+ for position, following in zip(positions, positions[1:]):
+ open_buckets += open_changes.get(position, 0)
+ # Reset when no bucket is open, so float error cannot leave a tiny density behind.
+ density = density + density_changes.get(position, 0.0) if open_buckets else 0.0
+ if density > 0:
+ merged[bisect.bisect_left(edges, following)] += density * (following - position)
+ return _Histogram(bounds=edges, counts=merged)
+
+
+def _resolution_edges(distributions: Sequence[_Histogram], edges: list[float]) -> list[float]:
+ """The merged edges that no source bucket with observations straddles.
+
+ Splitting a coarse bucket onto finer edges adds no precision, so only these edges tell how close
+ the quantile estimate is to the true value.
+ """
+ coverage = [0] * (len(edges) + 1)
+ for distribution in distributions:
+ for bucket in _source_buckets(distribution.bounds, distribution.counts):
+ start = bisect.bisect_right(edges, bucket.lower)
+ end = len(edges) if bucket.upper == math.inf else bisect.bisect_left(edges, bucket.upper)
+ if start < end:
+ coverage[start] += 1
+ coverage[end] -= 1
+ resolution: list[float] = []
+ straddled = 0
+ for index, edge in enumerate(edges):
+ straddled += coverage[index]
+ if not straddled:
+ resolution.append(edge)
+ return resolution
+
+
# Target about 60 chart buckets.
_TARGET_BUCKET_COUNT = 60
@@ -586,31 +751,59 @@ class MetricQueryRunner:
)
self._raise_on_truncation(response.results)
- group_count = len(self.group_by)
- distinct_bounds = {tuple(variant) for row in response.results for variant in row[2 + group_count] if variant}
- if len(distinct_bounds) > 1:
- raise ValueError(
- "histogram bounds differ across the selected series/time range; "
- "narrow the query with filters so all series share one bucket layout"
- )
-
rows: list[dict[str, Any]] = []
- for row in response.results:
- bounds = list(row[1 + group_count])
- counts = list(row[3 + group_count])
+ for key, merged in self.merged_distributions(response.results).items():
+ bounds, counts = merged.bounds, merged.counts
if sum(counts) <= 0:
# The bucket has no computable increase. Return a gap, not zero.
continue
rows.append(
{
- "time": row[0].isoformat() if isinstance(row[0], dt.datetime) else row[0],
+ "time": key[0].isoformat() if isinstance(key[0], dt.datetime) else key[0],
"value": _finite_or_none(_histogram_quantile(self.quantile, bounds, counts)),
- "labels": {group.key: row[1 + index] for index, group in enumerate(self.group_by)},
- "series_fingerprints": row[4 + group_count],
+ "labels": {group.key: key[1 + index] for index, group in enumerate(self.group_by)},
+ "series_fingerprints": sorted(merged.fingerprints),
+ "histogram_bounds": merged.resolution_bounds,
}
)
return rows
+ def merged_distributions(
+ self, results: list[Any], edges: Sequence[float] = ()
+ ) -> dict[tuple[Any, ...], MergedDistribution]:
+ """Merge the rows of `_build_histogram_query` into one distribution per (time, *group labels).
+
+ Each row holds one bucket layout. Exponential layouts move between emissions and custom
+ buckets differ per series, so the layouts of one time bucket merge before the quantile.
+ Pass `edges` to merge every distribution onto at least those edges.
+ """
+ group_count = len(self.group_by)
+ layouts: dict[tuple[Any, ...], list[_Histogram]] = {}
+ fingerprints: dict[tuple[Any, ...], set[int]] = {}
+ for row in results:
+ key = tuple(row[: 1 + group_count])
+ layouts.setdefault(key, []).append(_row_distribution(row, group_count))
+ fingerprints.setdefault(key, set()).update(row[3 + group_count])
+ extra = [_Histogram(bounds=list(edges), counts=[0.0] * (len(edges) + 1))] if edges else []
+ merged: dict[tuple[Any, ...], MergedDistribution] = {}
+ for key, distributions in layouts.items():
+ histogram = _merge_histograms([*distributions, *extra])
+ merged[key] = MergedDistribution(
+ bounds=histogram.bounds,
+ counts=histogram.counts,
+ resolution_bounds=_resolution_edges(distributions, histogram.bounds),
+ fingerprints=fingerprints[key],
+ )
+ return merged
+
+ def histogram_edges(self, results: list[Any]) -> list[float]:
+ """The union of the bucket upper edges in the rows of `_build_histogram_query`."""
+ group_count = len(self.group_by)
+ edges: set[float] = set()
+ for row in results:
+ edges.update(_row_distribution(row, group_count).bounds)
+ return sorted(edges)
+
def _raise_on_truncation(self, results: list[Any]) -> None:
"""Raise an error when the row limit drops recent buckets."""
if len(results) >= self._row_limit:
@@ -795,19 +988,21 @@ class MetricQueryRunner:
"""
SELECT
toStartOfInterval(sample_timestamp, {interval}) AS time,
- any(histogram_bounds) AS bounds,
- groupUniqArray(histogram_bounds) AS bounds_variants,
+ s.histogram_bounds AS bounds,
sumForEach(contribution_counts) AS counts,
- groupUniqArray(s.series_fingerprint) AS series_fingerprints
+ groupUniqArray(s.series_fingerprint) AS series_fingerprints,
+ s.metric_type AS metric_type
FROM (
SELECT
timestamp AS sample_timestamp,
series_fingerprint AS series_fingerprint,
histogram_bounds AS histogram_bounds,
+ metric_type AS metric_type,
multiIf(
aggregation_temporality = 'delta', counts_f,
empty(prev_counts), arrayMap(x -> 0.0, counts_f),
- length(prev_counts) != length(counts_f), counts_f,
+ prev_bounds != histogram_bounds OR length(prev_counts) != length(counts_f),
+ arrayMap(x -> 0.0, counts_f),
arrayAll((c, p) -> c >= p, counts_f, prev_counts), arrayMap((c, p) -> c - p, counts_f, prev_counts),
counts_f
) AS contribution_counts
@@ -817,17 +1012,23 @@ class MetricQueryRunner:
series_fingerprint,
aggregation_temporality,
histogram_bounds,
+ metric_type,
arrayMap(x -> toFloat(x), histogram_counts) AS counts_f,
lagInFrame(arrayMap(x -> toFloat(x), histogram_counts)) OVER (
PARTITION BY {series_key}
ORDER BY timestamp ASC
ROWS BETWEEN 1 PRECEDING AND 1 PRECEDING
- ) AS prev_counts
+ ) AS prev_counts,
+ lagInFrame(histogram_bounds) OVER (
+ PARTITION BY {series_key}
+ ORDER BY timestamp ASC
+ ROWS BETWEEN 1 PRECEDING AND 1 PRECEDING
+ ) AS prev_bounds
FROM {points}
)
) AS s
WHERE sample_timestamp >= {date_from}
- GROUP BY time
+ GROUP BY time, bounds, metric_type
ORDER BY time ASC
LIMIT {row_limit}
""",
@@ -841,6 +1042,7 @@ class MetricQueryRunner:
"aggregation_temporality",
"histogram_bounds",
"histogram_counts",
+ "metric_type",
),
point_filters=(parse_expr("notEmpty(histogram_counts)"),),
),
diff --git a/products/metrics/backend/presentation/api.py b/products/metrics/backend/presentation/api.py
index 5b4c316a0b97..797a824cdbcf 100644
--- a/products/metrics/backend/presentation/api.py
+++ b/products/metrics/backend/presentation/api.py
@@ -374,6 +374,12 @@ class _MetricSeriesSerializer(serializers.Serializer):
allow_null=True,
help_text='UCUM unit of the returned values, e.g. "By", "ms", "{request}/s". It is the ingested unit, except that a count of series has no unit and a rate is per second ("ms/s", or "1/s" for a counter without a unit). Null when the values have no unit, when merged series disagree on the unit, and for formula results.',
)
+ histogram_bounds = serializers.ListField(
+ child=serializers.FloatField(),
+ required=False,
+ allow_null=True,
+ help_text="Bucket upper edges a histogram_quantile series was estimated from. The true quantile can be anywhere between two edges. Null for other aggregations.",
+ )
class _MetricQueryResponseSerializer(serializers.Serializer):
diff --git a/products/metrics/backend/tests/test_metric_query_runner.py b/products/metrics/backend/tests/test_metric_query_runner.py
index 14d1dfee3b1a..2228f946f957 100644
--- a/products/metrics/backend/tests/test_metric_query_runner.py
+++ b/products/metrics/backend/tests/test_metric_query_runner.py
@@ -1564,16 +1564,53 @@ class TestHistogramQuantileRunner(ClickhouseTestMixin, APIBaseTest):
earliest = dt.datetime.fromisoformat(rows[0]["time"]).astimezone(dt.UTC)
self.assertEqual(earliest, self.anchor)
- def test_mismatched_bounds_raise(self):
- self._seed_histogram([(self.anchor + dt.timedelta(seconds=0), [1, 1, 1, 0])], temporality="delta")
+ def test_mismatched_bounds_merge_onto_one_layout(self):
+ # Two endpoints with their own buckets chart together instead of failing.
+ self._seed_histogram([(self.anchor + dt.timedelta(seconds=0), [10, 0, 0, 0])], temporality="delta")
self._seed_histogram(
- [(self.anchor + dt.timedelta(seconds=10), [1, 1, 1, 0])],
+ [(self.anchor + dt.timedelta(seconds=10), [0, 10, 0, 0])],
temporality="delta",
bounds=[0.2, 0.6, 2.0],
resource_labels={"k8s.pod.name": "other"},
)
- with self.assertRaises(ValueError):
- self._run(0.5)
+ rows = self._run(0.75)
+ self.assertEqual(len(rows), 1)
+ # Union edges [0.1, 0.2, 0.5, 0.6, 1.0, 2.0] get counts [10, 0, 7.5, 2.5, 0, 0, 0], so p75 is 2/3 into (0.2, 0.5].
+ self.assertAlmostEqual(rows[0]["value"], 0.4)
+ # The (0.2, 0.6] bucket holds observations, so the 0.5 edge adds no precision.
+ self.assertEqual(rows[0]["histogram_bounds"], [0.1, 0.2, 0.6, 1.0, 2.0])
+
+ def test_cumulative_bucket_count_change_does_not_fail(self):
+ # metrics4 keeps one bounds array per series-hour, so samples can carry more counts than bounds.
+ self._seed_histogram(
+ [
+ (self.anchor + dt.timedelta(seconds=0), [1, 1, 1, 0]),
+ (self.anchor + dt.timedelta(seconds=30), [2, 2, 2, 0, 0]),
+ ],
+ temporality="cumulative",
+ )
+ self.assertEqual(self._run(0.5), [])
+
+ def test_exponential_histogram_reads_upper_edges(self):
+ # Ingest stores lower edges [0.1, 0.2, 0.4]: every value is in (0.2, 0.4].
+ seed_metric(
+ team_id=self.team.id,
+ metric_name="latency",
+ metric_type="exponential_histogram",
+ aggregation_temporality="delta",
+ histogram_bounds=[0.1, 0.2, 0.4],
+ histogram_counts=[0, 10, 0],
+ points=[(self.anchor, 0.0)],
+ )
+ rows = self._run(0.5)
+ self.assertEqual(len(rows), 1)
+ self.assertAlmostEqual(rows[0]["value"], 0.3)
+ self.assertEqual(rows[0]["histogram_bounds"], [0.1, 0.2, 0.4, 0.8])
+
+ def test_rows_carry_the_bucket_edges(self):
+ self._seed_histogram([(self.anchor, [10, 10, 10, 0])], temporality="delta")
+ rows = self._run(0.5)
+ self.assertEqual(rows[0]["histogram_bounds"], self.BOUNDS)
def test_histogram_quantile_via_api(self):
self._seed_histogram(
@@ -1598,6 +1635,8 @@ class TestHistogramQuantileRunner(ClickhouseTestMixin, APIBaseTest):
points = response.json()["results"][0]["points"]
self.assertEqual(len(points), 1)
self.assertAlmostEqual(points[0]["value"], 0.3)
+ # The chart reads the edges to tell how coarse the estimate is.
+ self.assertEqual(response.json()["results"][0]["histogram_bounds"], self.BOUNDS)
def test_histogram_quantile_via_api_requires_quantile(self):
response = self.client.post(
diff --git a/products/metrics/backend/tests/test_metric_query_runner_unit.py b/products/metrics/backend/tests/test_metric_query_runner_unit.py
index ef0f27e58b0a..2e7cdfc00af1 100644
--- a/products/metrics/backend/tests/test_metric_query_runner_unit.py
+++ b/products/metrics/backend/tests/test_metric_query_runner_unit.py
@@ -7,7 +7,15 @@ from parameterized import parameterized
from posthog.hogql import ast
from products.metrics.backend.formula import evaluate, parse_formula
-from products.metrics.backend.metric_query_runner import _active_since_expr, _histogram_quantile, _pick_interval
+from products.metrics.backend.metric_query_runner import (
+ _active_since_expr,
+ _exponential_upper_edges,
+ _Histogram,
+ _histogram_quantile,
+ _merge_histograms,
+ _pick_interval,
+ _resolution_edges,
+)
class TestPickInterval:
@@ -49,6 +57,158 @@ class TestHistogramQuantileInterpolation:
assert abs(_histogram_quantile(q, bounds, counts) - expected) < 1e-9
+class TestExponentialUpperEdges:
+ # Ingest stores each exponential bucket's lower edge. The quantile reads upper edges.
+ @parameterized.expand(
+ [
+ ("positive_buckets", [1.0, 2.0, 4.0], [1, 2, 3], [1.0, 2.0, 4.0, 8.0], [0, 1, 2, 3]),
+ ("zero_bucket_first", [0.0, 1.0, 2.0], [5, 1, 1], [0.0, 1.0, 2.0, 4.0], [5, 0, 1, 1]),
+ # One bucket gives no base: it becomes a zero-width bucket at its lower edge, which is inside the true range.
+ ("one_bucket_sits_on_its_lower_edge", [1.0], [3], [1.0, 1.0], [0, 3]),
+ # Negative bucket i is [-base**(i+1), -base**i): ingest stores -base**i, closest to zero first.
+ ("negative_buckets_ascend", [-1.0, -2.0], [1, 2], [-4.0, -2.0, -1.0], [0, 2, 1]),
+ (
+ "zero_between_negative_and_positive",
+ [0.0, -1.0, -2.0, 1.0, 2.0],
+ [5, 1, 2, 3, 4],
+ # The zero bucket stays zero-width at 0 instead of spreading over (-1, 0].
+ [-4.0, -2.0, -1.0, 0.0, 0.0, 1.0, 2.0, 4.0],
+ [0, 2, 1, 0, 5, 0, 3, 4],
+ ),
+ ("empty", [], [], [], []),
+ (
+ # Repro: base=sqrt(2) between 2**-20 and 2**-19.5 computes 2**-19 one bit off from the
+ # stored bound, so a naive recompute inserts a spurious empty bucket and sorts out of order.
+ "consecutive_buckets_at_a_fine_scale_share_an_exact_edge",
+ [2**-20, 2**-19.5, 2**-19],
+ [5, 5, 5],
+ [2**-20, 2**-19.5, 2**-19, 2**-18.5],
+ [0, 5, 5, 5],
+ ),
+ (
+ "consecutive_buckets_at_a_coarse_scale_share_an_exact_edge",
+ [2**10, 2**10.5, 2**11],
+ [2, 3, 4],
+ [2**10, 2**10.5, 2**11, 2**11.5],
+ [0, 2, 3, 4],
+ ),
+ ]
+ )
+ def test_upper_edges(self, _name, bounds, counts, expected_bounds, expected_counts):
+ assert _exponential_upper_edges(bounds, counts) == (expected_bounds, expected_counts)
+
+ def test_upper_edges_are_always_sorted_ascending(self):
+ # The quantile and _resolution_edges both assume ascending edges; unsorted edges silently
+ # drop a real edge (see test_resolution_edges_keep_the_real_edge below).
+ edges, _ = _exponential_upper_edges([2**-20, 2**-19.5, 2**-19], [5, 5, 5])
+ assert edges == sorted(edges)
+
+ def test_resolution_edges_keep_the_real_edge(self):
+ # Before the fix, bisecting this unsorted edge list silently dropped the 2**-19 edge.
+ bounds, counts = _exponential_upper_edges([2**-20, 2**-19.5, 2**-19], [5, 5, 5])
+ histogram = _Histogram(bounds=bounds, counts=counts)
+ merged = _merge_histograms([histogram])
+ assert _resolution_edges([histogram], merged.bounds) == merged.bounds
+
+ @parameterized.expand(
+ [
+ ("positive", [0.1, 0.2, 0.4], [0, 10, 0], 0.3),
+ ("one_bucket", [1.0], [10], 1.0),
+ ("negative", [-1.0, -2.0, 1.0, 2.0], [0, 10, 0, 0], -3.0),
+ ]
+ )
+ def test_quantile_lands_inside_the_true_bucket(self, _name, bounds, counts, expected):
+ upper_bounds, upper_counts = _exponential_upper_edges(bounds, counts)
+ assert abs(_histogram_quantile(0.5, upper_bounds, upper_counts) - expected) < 1e-9
+
+
+class TestMergeHistograms:
+ @parameterized.expand(
+ [
+ (
+ "same_layout_sums",
+ [([0.1, 0.5], [1.0, 2.0, 3.0]), ([0.1, 0.5], [1.0, 2.0, 3.0])],
+ [0.1, 0.5],
+ [2.0, 4.0, 6.0],
+ ),
+ (
+ "coarse_bucket_splits_by_width",
+ [([1.0], [10.0, 0.0]), ([0.5, 1.0], [4.0, 6.0, 0.0])],
+ [0.5, 1.0],
+ [9.0, 11.0, 0.0],
+ ),
+ (
+ "overflow_goes_to_the_next_bucket_up",
+ [([1.0], [0.0, 3.0]), ([2.0, 4.0], [0.0, 0.0, 0.0])],
+ [1.0, 2.0, 4.0],
+ [0.0, 3.0, 0.0, 0.0],
+ ),
+ (
+ "overflow_above_every_edge_stays_overflow",
+ [([4.0], [0.0, 3.0]), ([2.0], [1.0, 0.0])],
+ [2.0, 4.0],
+ [1.0, 0.0, 3.0],
+ ),
+ ("one_layout_is_unchanged", [([0.1, 0.5], [1.0, 2.0, 3.0])], [0.1, 0.5], [1.0, 2.0, 3.0]),
+ (
+ "edges_from_an_empty_layout_still_split",
+ [([1.0], [10.0, 0.0]), ([0.5], [0.0, 0.0])],
+ [0.5, 1.0],
+ [5.0, 5.0, 0.0],
+ ),
+ ("no_edges_is_one_open_bucket", [([], [5.0]), ([1.0], [0.0, 0.0])], [1.0], [5.0, 0.0]),
+ (
+ "counts_past_the_edges_are_overflow",
+ [([1.0], [1.0, 2.0, 3.0]), ([2.0], [0.0, 0.0])],
+ [1.0, 2.0],
+ [1.0, 5.0, 0.0],
+ ),
+ (
+ "overlapping_layouts_spread_by_width",
+ [([1.0, 3.0], [0.0, 4.0, 0.0]), ([2.0, 4.0], [0.0, 4.0, 0.0])],
+ [1.0, 2.0, 3.0, 4.0],
+ [0.0, 2.0, 4.0, 2.0, 0.0],
+ ),
+ ]
+ )
+ def test_merge(self, _name, distributions, expected_bounds, expected_counts):
+ merged = _merge_histograms([_Histogram(bounds=bounds, counts=counts) for bounds, counts in distributions])
+ assert merged.bounds == expected_bounds
+ assert merged.counts == pytest.approx(expected_counts)
+
+ def test_total_count_is_kept(self):
+ merged = _merge_histograms(
+ [
+ _Histogram(bounds=[0.1, 0.3, 0.9], counts=[5.0, 7.0, 11.0, 2.0]),
+ _Histogram(bounds=[0.2, 1.0], counts=[3.0, 4.0, 1.0]),
+ ]
+ )
+ assert sum(merged.counts) == pytest.approx(33.0)
+
+
+class TestResolutionEdges:
+ @parameterized.expand(
+ [
+ ("one_layout_keeps_every_edge", [([0.1, 0.3], [1.0, 1.0, 0.0])], [0.1, 0.3]),
+ # Rebucketing a coarse (1, 10] bucket onto finer edges adds no precision.
+ (
+ "coarse_bucket_hides_finer_edges",
+ [([1.0, 10.0], [0.0, 4.0, 0.0]), ([2.0, 4.0, 10.0], [0.0] * 4)],
+ [1.0, 10.0],
+ ),
+ (
+ "empty_bucket_hides_nothing",
+ [([1.0, 10.0], [4.0, 0.0, 0.0]), ([2.0, 4.0], [0.0] * 3)],
+ [1.0, 2.0, 4.0, 10.0],
+ ),
+ ("overflow_hides_edges_above_it", [([1.0], [0.0, 3.0]), ([2.0, 4.0], [0.0] * 3)], [1.0]),
+ ]
+ )
+ def test_resolution_edges(self, _name, distributions, expected):
+ histograms = [_Histogram(bounds=bounds, counts=counts) for bounds, counts in distributions]
+ assert _resolution_edges(histograms, _merge_histograms(histograms).bounds) == expected
+
+
class TestFormulaParser:
@parameterized.expand(
[
diff --git a/products/metrics/backend/tests/test_metrics_histogram_query_runner.py b/products/metrics/backend/tests/test_metrics_histogram_query_runner.py
index db63b64a49a7..dcb7289fdec0 100644
--- a/products/metrics/backend/tests/test_metrics_histogram_query_runner.py
+++ b/products/metrics/backend/tests/test_metrics_histogram_query_runner.py
@@ -22,6 +22,7 @@ from posthog.models.personal_api_key import PersonalAPIKey
from posthog.models.utils import generate_random_token_personal, hash_key_value
from products.metrics.backend.hogql_queries.metrics_histogram_query_runner import MetricsHistogramQueryRunner
+from products.metrics.backend.metric_query_runner import MetricQueryRunner
from products.metrics.backend.tests._seeder import seed_metric, truncate_metrics_tables
@@ -121,19 +122,42 @@ class TestMetricsHistogramQueryRunner(ClickhouseTestMixin, APIBaseTest):
# an exponential histogram) blends into one heatmap.
def test_metric_type_filters_to_that_type(self):
self._seed_histogram([(self.anchor, [10, 10, 10, 0])])
- self._seed_histogram([(self.anchor, [5, 5, 5, 0])], metric_type="exponential_histogram")
+ # Ingest stores exponential lower edges; the grid rows are upper edges.
+ self._seed_histogram([(self.anchor, [5, 5, 5])], bounds=[0.1, 0.2, 0.4], metric_type="exponential_histogram")
response = self._run(metricType="exponential_histogram")
- second_minute = [response.counts[b][1] for b in range(len(self.BOUNDS))]
- self.assertEqual(second_minute, [5, 5, 5])
+ self.assertEqual(response.bounds, [0.1, 0.2, 0.4, 0.8])
+ self.assertEqual([row[1] for row in response.counts], [0, 5, 5, 5])
- def test_rejects_mixed_bucket_layouts(self):
+ def test_merged_counts_keep_their_total(self):
+ # (0, 1.0] splits over four finer buckets: 1 observation must not round away to 0.
+ self._seed_histogram([(self.anchor, [1, 0])], bounds=[1.0])
+ self._seed_histogram([(self.anchor, [0, 0, 0, 0, 0])], bounds=[0.25, 0.5, 0.75, 1.0])
+
+ response = self._run()
+
+ self.assertEqual(sum(row[1] for row in response.counts), 1)
+
+ def test_rejects_a_large_grid_before_merging(self):
+ self._seed_histogram([(self.anchor, [10, 0, 0, 0])])
+
+ with (
+ patch.object(MetricQueryRunner, "merged_distributions", side_effect=AssertionError("merged")),
+ patch("products.metrics.backend.hogql_queries.metrics_histogram_query_runner.MAX_GRID_CELLS", 1),
+ self.assertRaisesRegex(Exception, "heatmap grid would hold"),
+ ):
+ self._run()
+
+ def test_merges_mixed_bucket_layouts_onto_their_union(self):
self._seed_histogram([(self.anchor, [10, 0, 0, 0])], bounds=[0.1, 0.5, 1.0])
self._seed_histogram([(self.anchor, [10, 0, 0, 0])], bounds=[0.2, 1.0, 2.0])
- with self.assertRaises(Exception):
- self._run()
+ response = self._run()
+
+ self.assertEqual(response.bounds, [0.1, 0.2, 0.5, 1.0, 2.0])
+ # The (0, 0.2] bucket splits evenly over (0, 0.1] and (0.1, 0.2].
+ self.assertEqual([row[1] for row in response.counts], [15, 5, 0, 0, 0])
def test_no_trailing_column_when_date_to_sits_on_a_bucket_boundary(self):
# date_to is exclusive: a range ending exactly on a bucket start has no
diff --git a/products/metrics/backend/tests/test_metrics_query_languages.py b/products/metrics/backend/tests/test_metrics_query_languages.py
index 5ce80bf95796..8a401248e52e 100644
--- a/products/metrics/backend/tests/test_metrics_query_languages.py
+++ b/products/metrics/backend/tests/test_metrics_query_languages.py
@@ -222,7 +222,7 @@ class TestMetricsSqlMode(ClickhouseTestMixin, APIBaseTest):
if value is not None and actual_value is not None:
assert math.isclose(actual_value, value, rel_tol=1e-6, abs_tol=1e-9), (name, key, time)
- def test_mixed_histogram_bounds_fail_in_both_languages(self) -> None:
+ def test_mixed_histogram_bounds_merge_in_builder_but_fail_in_sql(self) -> None:
start = NOW - dt.timedelta(minutes=30)
for bounds, service in (([10.0], "api"), ([100.0], "worker")):
for m in range(0, 30):
@@ -237,8 +237,10 @@ class TestMetricsSqlMode(ClickhouseTestMixin, APIBaseTest):
)
fixture = FIXTURES["histogram p99"]
- with pytest.raises(ExposedHogQLError, match="histogram bounds differ"):
- self._run(clauses=[MetricsQueryClause(**clause) for clause in fixture["builder"]["clauses"]])
+ # The builder merges the layouts onto their union edges. SQL mode still asks for one layout.
+ results = self._run(clauses=[MetricsQueryClause(**clause) for clause in fixture["builder"]["clauses"]])
+ # The worker's (0, 100] bucket straddles the api's 10 edge, so the estimate is only accurate to 100.
+ assert results[0].histogramBounds == [100.0]
with pytest.raises(Exception, match="different histogram bounds"):
self._run(clauses=[], language="sql", sql=fixture["sql"])
diff --git a/products/metrics/frontend/components/MetricsPercentileResolutionHint.tsx b/products/metrics/frontend/components/MetricsPercentileResolutionHint.tsx
new file mode 100644
index 000000000000..3c3553c037b1
--- /dev/null
+++ b/products/metrics/frontend/components/MetricsPercentileResolutionHint.tsx
@@ -0,0 +1,124 @@
+import posthog from 'posthog-js'
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import { LemonBanner, LemonModal, LemonTag } from '@posthog/lemon-ui'
+
+import { CodeSnippet, Language } from 'lib/components/CodeSnippet'
+
+import { formatMetricValue } from '../panels/metricsUnits'
+import { coarsePercentileResolution, customBucketSnippet, suggestedBucketEdges } from './metricsPercentileResolution'
+import type { MetricsViewerSeries } from './metricsViewerLogic'
+
+const EXPONENTIAL_ENV = 'OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=base2_exponential_bucket_histogram'
+
+/** Warns that the percentile lines snap between a few wide buckets, and shows how to get sharper ones. */
+export function MetricsPercentileResolutionHint({
+ series,
+ metricName,
+}: {
+ series: MetricsViewerSeries[]
+ metricName: string | null
+}): JSX.Element | null {
+ const [guideOpen, setGuideOpen] = useState(false)
+ const resolution = useMemo(() => coarsePercentileResolution(series), [series])
+ const unit = series.find((s) => s.histogram_bounds?.length)?.unit ?? undefined
+ const suggested = useMemo(
+ () =>
+ suggestedBucketEdges(
+ series.flatMap((s) => (s.histogram_bounds?.length ? s.points.map((p) => p.value ?? 0) : []))
+ ),
+ [series]
+ )
+
+ // Live refresh reruns the query every few seconds, so count one view per metric.
+ const reportedMetric = useRef<string | null>(null)
+ useEffect(() => {
+ if (resolution && reportedMetric.current !== metricName) {
+ reportedMetric.current = metricName
+ posthog.capture('metrics percentile resolution hint shown', { edge_count: resolution.edges.length })
+ }
+ }, [resolution, metricName])
+
+ if (!resolution) {
+ return null
+ }
+ const format = (value: number): string => formatMetricValue(value, unit)
+ const bucket =
+ resolution.upper === Infinity
+ ? `above ${format(resolution.lower)}`
+ : resolution.lower <= 0
+ ? `below ${format(resolution.upper)}`
+ : `between ${format(resolution.lower)} and ${format(resolution.upper)}`
+ const metric = metricName ?? 'your_histogram'
+
+ return (
+ <>
+ <LemonBanner
+ type="info"
+ className="mt-2"
+ data-attr="metrics-percentile-resolution-hint"
+ action={{
+ children: 'Get sharper percentiles',
+ onClick: () => {
+ setGuideOpen(true)
+ posthog.capture('metrics percentile resolution guide opened')
+ },
+ }}
+ >
+ <div>
+ These percentiles are estimates from {resolution.edges.length} bucket edges. Most points are{' '}
+ <strong>{bucket}</strong>, and the lines can only move between these edges:{' '}
+ {resolution.edges.map(format).join(' · ')}.
+ </div>
+ </LemonBanner>
+ <LemonModal
+ isOpen={guideOpen}
+ onClose={() => setGuideOpen(false)}
+ title="Get sharper percentiles"
+ description="Percentiles are interpolated inside the bucket that holds them. Narrower buckets give lines you can trust. Change one service or endpoint at a time: series with different buckets still chart together."
+ width={720}
+ >
+ <div className="flex flex-col gap-6">
+ <section className="flex flex-col gap-2">
+ <div className="flex items-center gap-2">
+ <h4 className="m-0">Exponential histograms</h4>
+ <LemonTag type="success">Recommended</LemonTag>
+ </div>
+ <p className="m-0 text-secondary">
+ The SDK picks the buckets for each series, so every endpoint gets about 5% precision, fast
+ or slow. There is no bucket list to keep up to date. Set one environment variable on any
+ OpenTelemetry SDK:
+ </p>
+ <CodeSnippet
+ language={Language.Bash}
+ wrap
+ onCopy={() =>
+ posthog.capture('metrics percentile resolution snippet copied', {
+ option: 'exponential',
+ })
+ }
+ >
+ {EXPONENTIAL_ENV}
+ </CodeSnippet>
+ </section>
+ <section className="flex flex-col gap-2">
+ <h4 className="m-0">Custom buckets for one histogram</h4>
+ <p className="m-0 text-secondary">
+ Use this when you must keep a classic histogram, for example with a Prometheus client. These
+ edges cover what this chart shows:
+ </p>
+ <CodeSnippet
+ language={Language.Python}
+ wrap
+ onCopy={() =>
+ posthog.capture('metrics percentile resolution snippet copied', { option: 'custom' })
+ }
+ >
+ {customBucketSnippet(metric, unit ?? 's', suggested)}
+ </CodeSnippet>
+ </section>
+ </div>
+ </LemonModal>
+ </>
+ )
+}
diff --git a/products/metrics/frontend/components/MetricsViewer.tsx b/products/metrics/frontend/components/MetricsViewer.tsx
index 051ecb0b4c7f..ba813bfed0e3 100644
--- a/products/metrics/frontend/components/MetricsViewer.tsx
+++ b/products/metrics/frontend/components/MetricsViewer.tsx
@@ -24,6 +24,7 @@ import { MetricsFacetRailLayout, MetricsFacetRailToggle } from './FacetRail/Metr
import { MetricsAnomalyPanel } from './MetricsAnomalyPanel'
import { type MetricsExemplar } from './MetricsExemplarMarkers'
import { MetricsLogsSourceTag } from './MetricsLogsSourceTag'
+import { MetricsPercentileResolutionHint } from './MetricsPercentileResolutionHint'
import { MetricsQueryControls } from './MetricsQueryControls'
import { switchMetricsQueryLanguage } from './metricsQueryLanguageSwitch'
import { MetricsRelatedMenu } from './MetricsRelatedMenu'
@@ -60,6 +61,7 @@ export const MetricsViewer = (): JSX.Element => {
language,
queryText,
hasResults,
+ queryResults,
seriesCapReached,
displayType,
metricsDisplay,
@@ -327,6 +329,9 @@ export const MetricsViewer = (): JSX.Element => {
) : null}
{queryLoading && !isHeatmap && <SpinnerOverlay />}
</div>
+ {hasResults && !isHeatmap && !queryError && (
+ <MetricsPercentileResolutionHint series={queryResults} metricName={metricName} />
+ )}
</div>
{hasMetricName && (
<div className="xl:w-[26rem] shrink-0 xl:max-h-[360px] flex flex-col">
diff --git a/products/metrics/frontend/components/metricsPercentileResolution.test.ts b/products/metrics/frontend/components/metricsPercentileResolution.test.ts
new file mode 100644
index 000000000000..749b5d41a18b
--- /dev/null
+++ b/products/metrics/frontend/components/metricsPercentileResolution.test.ts
@@ -0,0 +1,100 @@
+import { OtelMetricTypeEnumApi } from '../generated/api.schemas'
+import { coarsePercentileResolution, customBucketSnippet, suggestedBucketEdges } from './metricsPercentileResolution'
+import { supportsHistogramQuantile } from './metricsViewerLogic'
+
+const DJANGO_BUCKETS = [0.1, 0.3, 0.9, 2.7, 8.1]
+
+const series = (
+ values: (number | null)[],
+ bounds: number[] | null = DJANGO_BUCKETS
+): { histogram_bounds: number[] | null; points: { time: string; value: number | null }[] } => ({
+ histogram_bounds: bounds,
+ points: values.map((value, index) => ({ time: `2026-10-23T10:0${index}:00Z`, value })),
+})
+
+describe('coarsePercentileResolution', () => {
+ it('names the bucket most points fall in when its edges are far apart', () => {
+ const resolution = coarsePercentileResolution([series([0.45, 0.5, 0.62, 1.2])])
+
+ expect(resolution).toEqual({ edges: DJANGO_BUCKETS, lower: 0.3, upper: 0.9, share: 0.75 })
+ })
+
+ it('counts a point below the first edge as the bucket from zero', () => {
+ expect(coarsePercentileResolution([series([0.05, 0.06])])).toMatchObject({ lower: 0, upper: 0.1 })
+ })
+
+ it('counts a point above the last edge as the open overflow bucket', () => {
+ expect(coarsePercentileResolution([series([9, 9.5])])).toMatchObject({ lower: 8.1, upper: Infinity })
+ })
+
+ it('stays quiet for fine buckets such as an exponential histogram', () => {
+ const fine = Array.from({ length: 40 }, (_, index) => 0.1 * 1.09 ** index)
+
+ expect(coarsePercentileResolution([series([0.45, 0.5, 0.62], fine)])).toBeNull()
+ })
+
+ it('stays quiet without histogram bounds or values', () => {
+ expect(coarsePercentileResolution([series([0.5], null)])).toBeNull()
+ expect(coarsePercentileResolution([series([null, null])])).toBeNull()
+ expect(coarsePercentileResolution([])).toBeNull()
+ })
+
+ it('finds the right bucket by binary search when there are many edges', () => {
+ // A handful of edges can't exercise a binary search's midpoint handling; this puts the
+ // target bucket in the middle of 1000 edges, where an off-by-one would show up.
+ const edges = [
+ ...Array.from({ length: 500 }, (_, index) => index + 1), // 1..500
+ 2000, // the busiest bucket, (500, 2000]
+ ...Array.from({ length: 499 }, (_, index) => index + 2001), // 2001..2499
+ ]
+
+ expect(coarsePercentileResolution([series([1000, 1000, 1000], edges)])).toMatchObject({
+ lower: 500,
+ upper: 2000,
+ share: 1,
+ })
+ })
+})
+
+describe('suggestedBucketEdges', () => {
+ it('spans the plotted values with edges that grow by a fixed step', () => {
+ const edges = suggestedBucketEdges([0.45, 1.2])
+
+ expect(edges[0]).toBeLessThanOrEqual(0.45 / 2)
+ expect(edges[edges.length - 1]).toBeGreaterThanOrEqual(1.2 * 2)
+ expect(edges.length).toBeLessThanOrEqual(12)
+ edges.slice(1).forEach((edge, index) => expect(edge / edges[index]).toBeLessThanOrEqual(1.6))
+ })
+
+ it('handles more values than a function call can take as arguments', () => {
+ const values = Array.from({ length: 1_000_000 }, (_, index) => 0.1 + (index % 100) / 100)
+
+ expect(() => suggestedBucketEdges(values)).not.toThrow()
+ })
+
+ it('returns no edges without positive values', () => {
+ expect(suggestedBucketEdges([])).toEqual([])
+ expect(suggestedBucketEdges([0])).toEqual([])
+ })
+})
+
+describe('customBucketSnippet', () => {
+ it('writes ingested names as string literals that cannot break out of the snippet', () => {
+ const unit = 's", description=__import__("os").system("id"), x="'
+
+ const snippet = customBucketSnippet('http.duration', unit, [0.1, 0.2])
+
+ expect(snippet).toContain(`unit=${JSON.stringify(unit)},`)
+ expect(snippet).not.toContain('description=__import__("os")')
+ expect(snippet).toContain('explicit_bucket_boundaries_advisory=[0.1, 0.2]')
+ expect(snippet).toContain('buckets=[0.1, 0.2, float("inf")]')
+ })
+})
+
+describe('supportsHistogramQuantile', () => {
+ it('offers percentiles for explicit and exponential histograms', () => {
+ expect(supportsHistogramQuantile(OtelMetricTypeEnumApi.Histogram)).toBe(true)
+ expect(supportsHistogramQuantile(OtelMetricTypeEnumApi.ExponentialHistogram)).toBe(true)
+ expect(supportsHistogramQuantile(OtelMetricTypeEnumApi.Gauge)).toBe(false)
+ })
+})
diff --git a/products/metrics/frontend/components/metricsPercentileResolution.ts b/products/metrics/frontend/components/metricsPercentileResolution.ts
new file mode 100644
index 000000000000..fbac187fdba2
--- /dev/null
+++ b/products/metrics/frontend/components/metricsPercentileResolution.ts
@@ -0,0 +1,132 @@
+/** A histogram percentile is interpolated inside the bucket that holds it, so it can only be as sharp as
+ * that bucket. A bucket whose upper edge is this many times its lower edge makes the line look precise
+ * while it only says "somewhere between these two edges". Exponential histograms stay far below it. */
+const COARSE_BUCKET_RATIO = 2
+/** Suggested custom edges grow by this factor, so the true value is at most about 25% from the estimate. */
+const SUGGESTED_EDGE_STEP = 1.5
+const MAX_SUGGESTED_EDGES = 12
+
+export interface PercentileResolution {
+ /** Every bucket upper edge the percentiles were estimated from. */
+ edges: number[]
+ /** The bucket that holds the most plotted points. `upper` is Infinity for the overflow bucket. */
+ lower: number
+ upper: number
+ /** Fraction of the plotted points in that bucket. */
+ share: number
+}
+
+interface PercentileSeries {
+ histogram_bounds?: number[] | null
+ points: { value: number | null }[]
+}
+
+/** The index of the first edge >= `value` in an ascending array, or -1 past the last edge. Mirrors
+ * `bounds.findIndex((bound) => value <= bound)`, but in O(log n): a histogram can carry tens of
+ * thousands of edges, and this runs per plotted point. */
+function upperEdgeIndex(bounds: number[], value: number): number {
+ let low = 0
+ let high = bounds.length
+ while (low < high) {
+ const mid = (low + high) >>> 1
+ if (bounds[mid] >= value) {
+ high = mid
+ } else {
+ low = mid + 1
+ }
+ }
+ return low === bounds.length ? -1 : low
+}
+
+/** The bucket that limits the percentile lines on a chart, or null when the buckets are fine enough. */
+export function coarsePercentileResolution(series: PercentileSeries[]): PercentileResolution | null {
+ const edges = new Set<number>()
+ const bucketCounts = new Map<string, { lower: number; upper: number; count: number }>()
+ let total = 0
+ for (const { histogram_bounds: bounds, points } of series) {
+ if (!bounds?.length) {
+ continue
+ }
+ bounds.forEach((bound) => edges.add(bound))
+ for (const { value } of points) {
+ if (value === null || !Number.isFinite(value)) {
+ continue
+ }
+ const index = upperEdgeIndex(bounds, value)
+ const lower =
+ index === -1 ? bounds[bounds.length - 1] : index > 0 ? bounds[index - 1] : Math.min(0, bounds[0])
+ const upper = index === -1 ? Infinity : bounds[index]
+ const key = `${lower}:${upper}`
+ const bucket = bucketCounts.get(key) ?? { lower, upper, count: 0 }
+ bucket.count += 1
+ bucketCounts.set(key, bucket)
+ total += 1
+ }
+ }
+ if (!total) {
+ return null
+ }
+ const busiest = [...bucketCounts.values()].reduce((best, bucket) => (bucket.count > best.count ? bucket : best))
+ if (busiest.lower > 0 && busiest.upper / busiest.lower < COARSE_BUCKET_RATIO) {
+ return null
+ }
+ return {
+ edges: [...edges].sort((a, b) => a - b),
+ lower: busiest.lower,
+ upper: busiest.upper,
+ share: busiest.count / total,
+ }
+}
+
+const floorToTwoSignificant = (value: number): number => {
+ const magnitude = 10 ** (Math.floor(Math.log10(value)) - 1)
+ return Number((Math.floor(value / magnitude) * magnitude).toPrecision(2))
+}
+
+/** Custom bucket edges that cover the plotted values with room on both sides. */
+export function suggestedBucketEdges(values: number[]): number[] {
+ // A loop, not Math.min(...values): a long chart exceeds the engine's argument limit.
+ let min = Infinity
+ let max = -Infinity
+ for (const value of values) {
+ if (Number.isFinite(value) && value > 0) {
+ min = Math.min(min, value)
+ max = Math.max(max, value)
+ }
+ }
+ if (min === Infinity) {
+ return []
+ }
+ const from = min / 2
+ const to = max * 2
+ const step = Math.max(SUGGESTED_EDGE_STEP, (to / from) ** (1 / (MAX_SUGGESTED_EDGES - 1)))
+ const edges: number[] = []
+ for (let edge = from; edges.length < MAX_SUGGESTED_EDGES; edge *= step) {
+ edges.push(floorToTwoSignificant(edge))
+ if (edges[edges.length - 1] >= to) {
+ break
+ }
+ }
+ return [...new Set(edges)]
+}
+
+/** Copy-paste examples that set custom buckets. Ingested names go in as escaped string literals, so a
+ * crafted metric name or unit cannot add code to the snippet. */
+export function customBucketSnippet(metric: string, unit: string, edges: number[]): string {
+ const list = edges.join(', ')
+ return [
+ '# OpenTelemetry',
+ 'meter.create_histogram(',
+ ` ${JSON.stringify(metric)},`,
+ ` unit=${JSON.stringify(unit)},`,
+ ` explicit_bucket_boundaries_advisory=[${list}],`,
+ ')',
+ '',
+ '# Prometheus client',
+ 'Histogram(',
+ ` ${JSON.stringify(metric)},`,
+ ' "...",',
+ ` buckets=[${list}, float("inf")],`,
+ ')',
+ ].join('\n')
+}
diff --git a/products/metrics/frontend/components/metricsViewerLogic.tsx b/products/metrics/frontend/components/metricsViewerLogic.tsx
index 5cf409e1cd84..0ed965bc4893 100644
--- a/products/metrics/frontend/components/metricsViewerLogic.tsx
+++ b/products/metrics/frontend/components/metricsViewerLogic.tsx
@@ -231,9 +231,12 @@ const HISTOGRAM_METRIC_TYPES: readonly OtelMetricTypeEnumApi[] = [
OtelMetricTypeEnumApi.Summary,
]
// Ingest keeps these types' bucket distribution apart from the scalar value, which holds the running
-// sum of observations. Exponential histograms are left out: ingest stores each bucket's lower edge,
-// and the backend quantile reads every bound as an upper edge.
-const HISTOGRAM_QUANTILE_METRIC_TYPES: readonly OtelMetricTypeEnumApi[] = [OtelMetricTypeEnumApi.Histogram]
+// sum of observations. The backend quantile turns the stored lower edges of exponential buckets into
+// upper edges.
+const HISTOGRAM_QUANTILE_METRIC_TYPES: readonly OtelMetricTypeEnumApi[] = [
+ OtelMetricTypeEnumApi.Histogram,
+ OtelMetricTypeEnumApi.ExponentialHistogram,
+]
export const supportsHistogramQuantile = (metricType: OtelMetricTypeEnumApi | null): boolean =>
!!metricType && HISTOGRAM_QUANTILE_METRIC_TYPES.includes(metricType)
@@ -1532,6 +1535,7 @@ export const metricsViewerLogic = kea<metricsViewerLogicType>([
metric_name: series.metricName ?? null,
clause: series.clause ?? null,
unit: series.unit ?? null,
+ histogram_bounds: series.histogramBounds ?? null,
}))
}
const queryPayload = values.queryPayload
diff --git a/products/metrics/frontend/generated/api.schemas.ts b/products/metrics/frontend/generated/api.schemas.ts
index bdf934b6db9b..9fd8b41dcd4c 100644
--- a/products/metrics/frontend/generated/api.schemas.ts
+++ b/products/metrics/frontend/generated/api.schemas.ts
@@ -239,6 +239,11 @@ export interface _MetricSeriesApi {
* @nullable
*/
unit?: string | null
+ /**
+ * Bucket upper edges a histogram_quantile series was estimated from. The true quantile can be anywhere between two edges. Null for other aggregations.
+ * @nullable
+ */
+ histogram_bounds?: number[] | null
}
export interface _MetricAnomalyReportApi {
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 411b1d2d25cf..bfd0ea977009 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -60073,6 +60073,8 @@ export namespace Schemas {
export interface MetricsQuerySeries {
/** Clause alias that produced this series (`formula` for the formula result) */
clause?: string | null;
+ /** Bucket upper edges a histogram quantile series was estimated from. The true quantile can be anywhere between two edges. */
+ histogramBounds?: number[] | null;
/** Label values identifying this series; empty for an ungrouped query */
labels: MetricsQuerySeriesLabels;
metricName?: string | null;
@@ -122395,6 +122397,11 @@ export namespace Schemas {
* @nullable
*/
unit?: string | null;
+ /**
+ * Bucket upper edges a histogram_quantile series was estimated from. The true quantile can be anywhere between two edges. Null for other aggregations.
+ * @nullable
+ */
+ histogram_bounds?: number[] | null;
}
export interface _MetricAnomalyReport {