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.

perf(metrics): run metric query clauses and the unit lookup in parallel (#122336)

Frank Hamandd5f900f0b229
diff --git a/products/metrics/backend/facade/api.py b/products/metrics/backend/facade/api.py
index c5198c5e40b9..f80fe34795f5 100644
--- a/products/metrics/backend/facade/api.py
+++ b/products/metrics/backend/facade/api.py
@@ -7,12 +7,15 @@ so import-linter's strict-mode contract holds.
import math
import datetime as dt
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
from contextlib import nullcontext
from dataclasses import replace
from functools import partial
from typing import Any
+from django.conf import settings
+from django.db import connection
+
import structlog
from posthog.schema import DateRange, MetricsDashboardVariable, MetricsDashboardVariableSource
@@ -24,6 +27,7 @@ from posthog.hogql.parser import parse_select
from posthog.hogql.query import execute_hogql_query
from posthog.clickhouse.client.connection import Workload
+from posthog.hogql_queries.utils.parallel import run_in_parallel_threads
from posthog.models import Team, User
from products.error_tracking.backend.facade.api import list_spike_events
@@ -65,7 +69,7 @@ from products.metrics.backend.metric_attributes_query_runner import (
)
from products.metrics.backend.metric_event_samples_query_runner import MetricEventSamplesQueryRunner
from products.metrics.backend.metric_names_query_runner import MetricNamesQueryRunner, cached_metric_names
-from products.metrics.backend.metric_query_runner import MAX_RAW_SERIES
+from products.metrics.backend.metric_query_runner import MAX_RAW_SERIES, MetricQueryRunner
from products.metrics.backend.metric_samples_query_runner import build_metric_query_runner
from products.metrics.backend.metrics_overview_query_runner import MetricsOverviewQueryRunner
from products.metrics.backend.query_concurrency import query_concurrency_slots
@@ -329,6 +333,14 @@ def _evaluate_formula(
return result
+def _closing_connection(work: Callable[[], None]) -> None:
+ try:
+ work()
+ finally:
+ # The query reads Postgres in the worker thread, and request cleanup only closes the request thread's connection.
+ connection.close()
+
+
def run_metric_query(*, team: Team, request: MetricQueryRequest) -> list[MetricSeries]:
"""Execute a metric query and return one `MetricSeries` per
(clause, label-set) pair — a single ungrouped clause yields exactly one
@@ -348,7 +360,7 @@ def run_metric_query(*, team: Team, request: MetricQueryRequest) -> list[MetricS
if request.formula is not None
else None
)
- rows_by_clause: dict[str, list[dict[str, Any]]] = {}
+ runners: list[tuple[MetricQueryClause, MetricQueryRunner, bool]] = []
for clause in request.clauses:
runner_aggregation = _resolve_runner_aggregation(clause)
runner = build_metric_query_runner(
@@ -364,25 +376,39 @@ def run_metric_query(*, team: Team, request: MetricQueryRequest) -> list[MetricS
metric_type=clause.metric_type.value if clause.metric_type is not None else None,
range_function=clause.range_function.value if clause.range_function is not None else None,
)
+ runners.append((clause, runner, runner_aggregation is None))
+ rows_by_clause: dict[str, list[dict[str, Any]]] = {clause.name: [] for clause in request.clauses}
+ units_by_fingerprint: dict[int, str] = {}
+
+ def run_clause(clause: MetricQueryClause, runner: MetricQueryRunner, raw: bool) -> None:
rows = runner.run()
- if runner_aggregation is None:
+ if raw:
_attach_series_labels(team, clause.metric_name, rows)
rows_by_clause[clause.name] = rows
+ def load_units() -> None:
+ units_by_fingerprint.update(_units_by_fingerprint(team, {clause.metric_name for clause in request.clauses}))
+
+ # The clause queries and the unit lookup do not depend on each other, so a tile waits for the slowest one,
+ # not for their sum. A formula combines clauses of different units, so its series carry no unit.
+ work: list[Callable[[], None]] = [partial(run_clause, *item) for item in runners]
+ if formula_node_checked is None:
+ work.append(load_units)
+ # Django does not make the test transaction visible to another thread.
+ if len(work) <= 1 or settings.IN_UNIT_TESTING:
+ for item in work:
+ item()
+ else:
+ run_in_parallel_threads(
+ [partial(_closing_connection, item) for item in work], thread_name_prefix="metrics_clauses"
+ )
+
grid = sorted({row["time"] for rows in rows_by_clause.values() for row in rows})
if not grid:
empty_clause = "formula" if formula_node_checked is not None else request.clauses[0].name
metric_name = None if formula_node_checked is not None else request.clauses[0].metric_name
return [MetricSeries(labels={}, points=(), metric_name=metric_name, clause=empty_clause)]
- # A formula combines clauses (possibly of different units), so its series
- # carry no unit and the unit lookup is skipped entirely.
- units_by_fingerprint = (
- {}
- if formula_node_checked is not None
- else _units_by_fingerprint(team, {clause.metric_name for clause in request.clauses})
- )
-
series_by_clause = {
clause.name: _assemble_series(
rows_by_clause[clause.name],
diff --git a/products/metrics/backend/tests/test_metric_query_runner.py b/products/metrics/backend/tests/test_metric_query_runner.py
index 01751a283a03..14d1dfee3b1a 100644
--- a/products/metrics/backend/tests/test_metric_query_runner.py
+++ b/products/metrics/backend/tests/test_metric_query_runner.py
@@ -1,4 +1,5 @@
import datetime as dt
+import threading
from typing import Any
from zoneinfo import ZoneInfo
@@ -6,7 +7,7 @@ import pytest
from posthog.test.base import APIBaseTest, ClickhouseTestMixin
from unittest.mock import patch
-from django.test import SimpleTestCase
+from django.test import SimpleTestCase, override_settings
from django.utils import timezone
from parameterized import parameterized
@@ -18,6 +19,7 @@ from posthog.hogql.query import execute_hogql_query
from posthog.clickhouse.client import sync_execute
from posthog.clickhouse.client.connection import Workload
+from posthog.models import Team
from products.metrics.backend.facade.api import _output_unit, run_metric_query
from products.metrics.backend.facade.contracts import MetricFilter, MetricGroupBy, MetricQueryClause, MetricQueryRequest
@@ -870,6 +872,47 @@ class TestRunMetricQueryFacade(ClickhouseTestMixin, APIBaseTest):
run_metric_query(team=self.team, request=self._request(**overrides))
+class TestRunMetricQueryInParallel(SimpleTestCase):
+ def test_the_clause_queries_and_the_unit_lookup_run_at_the_same_time_and_close_their_connections(self) -> None:
+ # Each query waits until all three run, so a serial run breaks the barrier.
+ barrier = threading.Barrier(3, timeout=5)
+ anchor = dt.datetime(2026, 1, 1, 12, tzinfo=dt.UTC)
+
+ class _Runner:
+ def run(self) -> list[dict[str, Any]]:
+ barrier.wait()
+ return [{"time": anchor.isoformat(), "value": 1.0, "labels": {}, "series_fingerprints": [1]}]
+
+ def units(_team: Team, _names: set[str]) -> dict[int, str]:
+ barrier.wait()
+ return {1: "ms"}
+
+ with (
+ override_settings(IN_UNIT_TESTING=False),
+ patch("products.metrics.backend.facade.api.build_metric_query_runner", side_effect=lambda **_: _Runner()),
+ patch("products.metrics.backend.facade.api._units_by_fingerprint", side_effect=units),
+ patch("products.metrics.backend.facade.api.connection") as connection,
+ ):
+ series = run_metric_query(
+ team=Team(id=1),
+ request=MetricQueryRequest(
+ clauses=(
+ MetricQueryClause(name="a", metric_name="m1", aggregation=MetricAggregation.SUM),
+ MetricQueryClause(name="b", metric_name="m2", aggregation=MetricAggregation.SUM),
+ ),
+ date_from=anchor - dt.timedelta(hours=1),
+ date_to=anchor,
+ ),
+ )
+
+ assert [(item.clause, item.unit, [point.value for point in item.points]) for item in series] == [
+ ("a", "ms", [1.0]),
+ ("b", "ms", [1.0]),
+ ]
+ # Each worker closes the Postgres connection that it opened.
+ assert connection.close.call_count == 3
+
+
class TestOutputUnit(SimpleTestCase):
@parameterized.expand(
[