: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(metrics): sharper histogram percentiles across bucket layouts (#122465)
Daniel Visca36806304df62
diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.jsonindex 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.tsindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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 mathimport datetime as dtfrom datetime import datetimefrom 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: MetricsHistogramQuerycached_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[MetricsHistogramQueryRespf"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[MetricsHistogramQueryRespcolumn = 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.pyindex 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.pyindex 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 reimport math+import bisectimport datetime as dt-from collections.abc import Sequence-from typing import Any, Literal+from collections.abc import Iterator, Sequence+from typing import Any, Literal, NamedTuplefrom zoneinfo import ZoneInfofrom posthog.hogql import ast@@ -19,6 +20,7 @@ from posthog.hogql.parser import parse_expr, parse_selectfrom posthog.hogql.query import execute_hogql_queryfrom posthog.clickhouse.client.connection import Workload+from posthog.dataclasses import frozenfrom posthog.models import Teamfrom products.metrics.backend.facade.contracts import MetricFilter, MetricGroupBy, MetricQueryTooManyRowsError@@ -154,6 +156,169 @@ def _histogram_quantile(quantile: float, bounds: list[float], counts: list[floatreturn 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.countsif sum(counts) <= 0:# The bucket has no computable increase. Return a gap, not zero.continuerows.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:"""SELECTtoStartOfInterval(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_typeFROM (SELECTtimestamp 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 ASCROWS 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_boundsFROM {points})) AS sWHERE sample_timestamp >= {date_from}- GROUP BY time+ GROUP BY time, bounds, metric_typeORDER BY time ASCLIMIT {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.pyindex 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.pyindex 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.pyindex 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 parameterizedfrom posthog.hogql import astfrom 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.pyindex 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 PersonalAPIKeyfrom posthog.models.utils import generate_random_token_personal, hash_key_valuefrom products.metrics.backend.hogql_queries.metrics_histogram_query_runner import MetricsHistogramQueryRunner+from products.metrics.backend.metric_query_runner import MetricQueryRunnerfrom 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 nodiff --git a/products/metrics/backend/tests/test_metrics_query_languages.py b/products/metrics/backend/tests/test_metrics_query_languages.pyindex 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.tsxnew file mode 100644index 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.tsxindex 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/Metrimport { 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.queryPayloaddiff --git a/products/metrics/frontend/generated/api.schemas.ts b/products/metrics/frontend/generated/api.schemas.tsindex 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.tsindex 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 {