: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): count queries per metric and expose them in the API (#129619)
Daniel Visca1987a34aa4e1
diff --git a/.semgrep/rules/security/idor-team-scoped-models.yaml b/.semgrep/rules/security/idor-team-scoped-models.yamlindex 6e82cb05ae9d..1844844a287c 100644--- a/.semgrep/rules/security/idor-team-scoped-models.yaml+++ b/.semgrep/rules/security/idor-team-scoped-models.yaml@@ -307,6 +307,7 @@ rules:|MessageSuppression|MessageTemplate|Metric+ |MetricDailyQueryCount|MetricsDashboardDiscovery|MetricsDashboardSuggestion|RelationshipProposal@@ -812,6 +813,7 @@ rules:|MessageSuppression|MessageTemplate|Metric+ |MetricDailyQueryCount|MetricsDashboardDiscovery|MetricsDashboardSuggestion|RelationshipProposaldiff --git a/posthog/api/snuffle_proxy.py b/posthog/api/snuffle_proxy.pyindex 0d7275d0d99f..471dea4a75af 100644--- a/posthog/api/snuffle_proxy.py+++ b/posthog/api/snuffle_proxy.py@@ -184,6 +184,9 @@ class SnuffleProxyViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):return []return super().get_throttles()+ def before_forward(self, request: Request, path: str) -> None:+ """Runs once for each request that the proxy forwards upstream. Subclasses override it."""+@extend_schema(exclude=True)@action(detail=False, methods=["GET", "POST"], url_path=r"api/v1/(?P<path>[A-Za-z0-9_./-]+)")def proxy(self, request: Request, path: str, **kwargs) -> HttpResponse:@@ -210,6 +213,7 @@ class SnuffleProxyViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):response["Retry-After"] = str(budget_status.retry_after_seconds)return response+ self.before_forward(request, path)method = request.method or "GET"body = _forwardable(request.data) if method == "POST" and isinstance(request.data, QueryDict) else Nonediff --git a/products/metrics/backend/facade/api.py b/products/metrics/backend/facade/api.pyindex 0e7b96683579..bbff2b443f7c 100644--- a/products/metrics/backend/facade/api.py+++ b/products/metrics/backend/facade/api.py@@ -46,6 +46,7 @@ from products.metrics.backend.facade.contracts import (MetricFilter,MetricPoint,MetricQueryClause,+ MetricQueryCount,MetricQueryRequest,MetricSeries,MetricsOverview,@@ -79,6 +80,11 @@ from products.metrics.backend.metric_samples_query_runner import build_metric_qufrom products.metrics.backend.metrics_overview_query_runner import MetricsOverviewQueryRunnerfrom products.metrics.backend.promql import run_promql_rangefrom products.metrics.backend.query_concurrency import query_concurrency_slots+from products.metrics.backend.query_counts import (+ list_metric_query_counts as _list_metric_query_counts,+ record_metric_queries,+ record_promql_query as _record_promql_query,+)from products.metrics.backend.variable_options import check_options_window, compile_regex, list_variable_optionsfrom products.metrics.backend.variables import from_dashboard, with_values@@ -371,6 +377,7 @@ def run_metric_query(*, team: Team, request: MetricQueryRequest) -> list[MetricSif request.formula is not Noneelse None)+ record_metric_queries(team, (clause.metric_name for clause in request.clauses))runners: list[tuple[MetricQueryClause, MetricQueryRunner, bool]] = []for clause in request.clauses:runner_aggregation = _resolve_runner_aggregation(clause)@@ -445,6 +452,16 @@ def run_metric_query(*, team: Team, request: MetricQueryRequest) -> list[MetricS]+def list_metric_query_counts(*, team: Team, days: int, limit: int) -> list[MetricQueryCount]:+ """How often queries read each metric of the team in the last `days` UTC days, the most queried first."""+ return _list_metric_query_counts(team, days=days, limit=limit)+++def record_promql_query(*, team: Team, expr: str) -> None:+ """Count one query for each metric that a PromQL expression selects. A failed write never raises."""+ _record_promql_query(team, expr)++def run_promql_query(*, team: Team, expr: str, date_from: dt.datetime, date_to: dt.datetime, interval: str | None) -> list[MetricSeries]:diff --git a/products/metrics/backend/facade/contracts.py b/products/metrics/backend/facade/contracts.pyindex a134cb30c1cd..a27c111e56ca 100644--- a/products/metrics/backend/facade/contracts.py+++ b/products/metrics/backend/facade/contracts.py@@ -42,6 +42,9 @@ from .enums import (# Each clause runs its own ClickHouse query on the shared logs cluster, so# the clause count per request is hard-capped.MAX_CLAUSES_PER_QUERY = 10+DEFAULT_QUERY_COUNT_DAYS = 30+MAX_QUERY_COUNT_DAYS = 90+MAX_PROMQL_LENGTH = 8192MAX_SPARKLINE_BATCH_SIZE = 20@@ -410,6 +413,21 @@ class MetricsOverview:services: tuple[MetricsServiceOverview, ...]+@dataclass(frozen=True, slots=True)+class MetricQueryCount:+ """How often queries read one metric of a team inside a window of days.++ A query counts once for each metric that it selects, whatever the number of clauses or selectors that name it.+ Builder, heatmap and PromQL queries count, from the app, alerts and the Prometheus API.+ SQL mode queries do not count.+ A PromQL selector that names no metric, such as `{__name__=~"http_.*"}`, counts nothing.+ """++ metric_name: str+ query_count: int+ last_queried_at: dt.datetime++class DashboardImportError(ValueError):"""A dashboard import cannot start or continue. The message is safe to show to the user."""diff --git a/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py b/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.pyindex c4a66d368476..2690c7f7a353 100644--- a/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py+++ b/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py@@ -34,6 +34,7 @@ from products.metrics.backend.facade.contracts import METRICS_FEATURE_FLAG, Metrfrom products.metrics.backend.facade.enums import AttributeScope, FilterOpfrom products.metrics.backend.metric_query_runner import _INTERVAL_LADDER, _QUERY_SETTINGS, _interval_stepfrom products.metrics.backend.metric_samples_query_runner import build_metric_query_runner+from products.metrics.backend.query_counts import record_metric_queriesfrom products.metrics.backend.query_interval import resolve_query_intervalfrom products.metrics.backend.variables import (filter_referenced_names,@@ -159,6 +160,7 @@ class MetricsHistogramQueryRunner(AnalyticsQueryRunner[MetricsHistogramQueryResp# errors, so a bare ValueError would surface as a 500 instead of a 400.raise ExposedHogQLError(str(exc)) from exc+ record_metric_queries(self.team, [self.query.metricName])# Reuse the per-bucket distribution query directly rather than the quantile post-processing.query = runner._build_histogram_query()response = execute_hogql_query(diff --git a/products/metrics/backend/migrations/0003_metricdailyquerycount.py b/products/metrics/backend/migrations/0003_metricdailyquerycount.pynew file mode 100644index 000000000000..150935824404--- /dev/null+++ b/products/metrics/backend/migrations/0003_metricdailyquerycount.py@@ -0,0 +1,52 @@+# Generated by Django 6.1.3 on 2026-11-04 19:49++import django.db.models.deletion+from django.db import migrations, models++import posthog.uuidt+++class Migration(migrations.Migration):+ dependencies = [+ ("metrics", "0002_metricsdashboardtemplate_variables"),+ ("posthog", "1424_workload_trust_policy"),+ ]++ operations = [+ migrations.CreateModel(+ name="MetricDailyQueryCount",+ fields=[+ (+ "id",+ models.UUIDField(+ default=posthog.uuidt.uuid7,+ editable=False,+ primary_key=True,+ serialize=False,+ ),+ ),+ ("metric_name", models.CharField(max_length=400)),+ ("date", models.DateField()),+ ("query_count", models.BigIntegerField(default=0)),+ ("last_queried_at", models.DateTimeField()),+ (+ "team",+ models.ForeignKey(+ db_constraint=False,+ on_delete=django.db.models.deletion.CASCADE,+ related_name="+",+ to="posthog.team",+ ),+ ),+ ],+ options={+ "indexes": [models.Index(fields=["team", "date"], name="metrics_dqc_team_date_idx")],+ "constraints": [+ models.UniqueConstraint(+ fields=("team", "metric_name", "date"),+ name="metrics_daily_query_count_unique",+ )+ ],+ },+ ),+ ]diff --git a/products/metrics/backend/migrations/max_migration.txt b/products/metrics/backend/migrations/max_migration.txtindex 0b4d40f8d207..93cd1ea33810 100644--- a/products/metrics/backend/migrations/max_migration.txt+++ b/products/metrics/backend/migrations/max_migration.txt@@ -1 +1 @@-0002_metricsdashboardtemplate_variables+0003_metricdailyquerycountdiff --git a/products/metrics/backend/models.py b/products/metrics/backend/models.pyindex 8eac6d655941..23e60d90e9df 100644--- a/products/metrics/backend/models.py+++ b/products/metrics/backend/models.py@@ -132,3 +132,19 @@ class MetricsDashboardDiscovery(TeamScopedRootMixin, UUIDModel):class Meta:constraints = [models.UniqueConstraint(fields=["team"], name="metrics_dash_discovery_unique_team")]+++class MetricDailyQueryCount(TeamScopedRootMixin, UUIDModel):+ """How many queries read a metric of a team on one UTC day."""++ team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, related_name="+", db_constraint=False)+ metric_name = models.CharField(max_length=400)+ date = models.DateField()+ query_count = models.BigIntegerField(default=0)+ last_queried_at = models.DateTimeField()++ class Meta:+ constraints = [+ models.UniqueConstraint(fields=["team", "metric_name", "date"], name="metrics_daily_query_count_unique")+ ]+ indexes = [models.Index(fields=["team", "date"], name="metrics_dqc_team_date_idx")]diff --git a/products/metrics/backend/presentation/api.py b/products/metrics/backend/presentation/api.pyindex ebe2ecc6e7de..1ce8b728d34e 100644--- a/products/metrics/backend/presentation/api.py+++ b/products/metrics/backend/presentation/api.py@@ -46,13 +46,17 @@ from products.metrics.backend.facade.api import (list_metric_event_samples,list_metric_names,list_metric_picker_names,+ list_metric_query_counts,list_metric_variable_options,run_metric_query,run_promql_query,team_has_metrics,)from products.metrics.backend.facade.contracts import (+ DEFAULT_QUERY_COUNT_DAYS,MAX_CLAUSES_PER_QUERY,+ MAX_PROMQL_LENGTH,+ MAX_QUERY_COUNT_DAYS,MAX_SPARKLINE_BATCH_SIZE,METRICS_ERROR_OVERLAYS_FEATURE_FLAG,METRICS_FEATURE_FLAG,@@ -291,7 +295,7 @@ class _MetricQueryBodySerializer(serializers.Serializer):promql = serializers.CharField(required=False,allow_null=True,- max_length=8192,+ max_length=MAX_PROMQL_LENGTH,help_text="PromQL expression, run as a range query over the request's time grid, e.g. 'sum by (job) (rate(http_requests_total[5m]))'. Use it to run an alert or runbook expression as written. Mutually exclusive with 'metricName' and 'clauses'; put label selectors and grouping in the expression instead of 'filters' and 'groupBy'. In PromQL, service.name is service_name and other label names with dots need quotes. A bucket that a series did not report is null, not zero.",)dateFrom = _RelativeOrIsoDateTimeField(@@ -644,6 +648,32 @@ class _MetricPickerNamesResponseSerializer(serializers.Serializer):results = _MetricPickerNameSerializer(many=True, help_text="Distinct metric names ordered by recent activity.")+class _MetricQueryCountsParamsSerializer(serializers.Serializer):+ days = serializers.IntegerField(+ default=DEFAULT_QUERY_COUNT_DAYS,+ min_value=1,+ max_value=MAX_QUERY_COUNT_DAYS,+ help_text="Number of UTC days to count, today included.",+ )+ limit = serializers.IntegerField(+ default=100, min_value=1, max_value=1000, help_text="Maximum number of metrics to return."+ )+++class _MetricQueryCountSerializer(serializers.Serializer):+ metric_name = serializers.CharField(help_text="Metric name as it appears in the team's data.")+ query_count = serializers.IntegerField(+ help_text="Number of builder and PromQL queries that read the metric in the window. SQL mode queries do not count."+ )+ last_queried_at = serializers.DateTimeField(help_text="When a query last read the metric, ISO 8601.")+++class _MetricQueryCountsResponseSerializer(serializers.Serializer):+ results = _MetricQueryCountSerializer(+ many=True, help_text="Metrics that queries read in the window, the most queried first."+ )++class _MetricAttributeKeysParamsSerializer(serializers.Serializer):metricName = serializers.CharField(required=False,@@ -1104,6 +1134,33 @@ class MetricsViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):return Response({"results": results}, status=status.HTTP_200_OK)+ @extend_schema(+ parameters=[_MetricQueryCountsParamsSerializer],+ responses={200: _MetricQueryCountsResponseSerializer},+ )+ @action(detail=False, methods=["GET"], required_scopes=["metrics:read"])+ def query_counts(self, request: Request, *args, **kwargs) -> Response:+ """How often queries read each metric of the team. A metric that no query reads is not in the list."""+ params = _MetricQueryCountsParamsSerializer(data=request.query_params)+ params.is_valid(raise_exception=True)++ counts = list_metric_query_counts(+ team=self.team, days=params.validated_data["days"], limit=params.validated_data["limit"]+ )++ report_user_action(+ request.user,+ "metrics query counts viewed",+ {"days": params.validated_data["days"], "metric_count": len(counts)},+ team=self.team,+ request=request,+ )++ return Response(+ _MetricQueryCountsResponseSerializer({"results": [asdict(count) for count in counts]}).data,+ status=status.HTTP_200_OK,+ )+@extend_schema(parameters=[_MetricAttributeKeysParamsSerializer],responses={200: _MetricAttributeKeysResponseSerializer},diff --git a/products/metrics/backend/presentation/prometheus_api.py b/products/metrics/backend/presentation/prometheus_api.pyindex fa5f7d539e8a..5e2341006e73 100644--- a/products/metrics/backend/presentation/prometheus_api.py+++ b/products/metrics/backend/presentation/prometheus_api.py@@ -1,7 +1,11 @@import re+from rest_framework.request import Request+from posthog.api.snuffle_proxy import SnuffleProxyViewSet+from products.metrics.backend.facade.api import record_promql_query+_LABEL_NAME = r"[A-Za-z_][A-Za-z0-9_]*"@@ -27,3 +31,11 @@ class PrometheusQueryViewSet(SnuffleProxyViewSet):re.compile(r"alerts"),re.compile(r"status/buildinfo"),)++ def before_forward(self, request: Request, path: str) -> None:+ if path not in ("query", "query_range"):+ return+ # The Prometheus API takes the query from the form body of a POST or from the query string.+ expr = request.data.get("query") or request.query_params.get("query")+ if expr:+ record_promql_query(team=self.team, expr=expr)diff --git a/products/metrics/backend/promql.py b/products/metrics/backend/promql.pyindex 46e3f2af1e55..fbd571110add 100644--- a/products/metrics/backend/promql.py+++ b/products/metrics/backend/promql.py@@ -16,10 +16,12 @@ from posthog.models import Teamfrom products.metrics.backend.facade.contracts import MetricPoint, MetricSeries, PromQLQueryErrorfrom products.metrics.backend.metric_query_runner import _align_to_interval, _interval_step, _resolve_interval+from products.metrics.backend.query_counts import record_promql_queryfrom products.metrics.backend.series import rank_and_fill_series# The label that builderToPromql adds to keep the series of a multi-series query apart.CLAUSE_LABEL = "clause"+_QUERY_PATHS = frozenset({"/api/v1/query", "/api/v1/query_range"})# builderToPromql sets the label with `label_replace(<series>, "clause", "<alias>", "", "")`. Without# that call, a `clause` label belongs to the user's data._SETS_CLAUSE_LABEL = re.compile(r'label_replace\s*\(.*,\s*"clause"\s*,\s*"', re.DOTALL)@@ -78,6 +80,8 @@ def snuffle_payload(timeout: float | None = None,) -> dict[str, Any]:"""Send one Prometheus API request to Snuffle and return its JSON body. Errors are safe to show."""+ if path in _QUERY_PATHS and data and data.get("query"):+ record_promql_query(team, data["query"])try:response = snuffle_request(team.pk, method, path, data=data, params=params, timeout=timeout)except SnuffleNotConfiguredError as exc:diff --git a/products/metrics/backend/query_counts.py b/products/metrics/backend/query_counts.pynew file mode 100644index 000000000000..eef107832609--- /dev/null+++ b/products/metrics/backend/query_counts.py@@ -0,0 +1,93 @@+"""Per-metric query counts, so that a team can see which metrics its queries read and which they never read."""++import datetime as dt+from collections.abc import Iterable+from uuid import UUID++from django.db import DatabaseError, connections, router, transaction+from django.db.models import Max, Sum+from django.utils import timezone++import structlog++from posthog.exceptions_capture import capture_exception+from posthog.models import Team++from products.metrics.backend.facade.contracts import DEFAULT_QUERY_COUNT_DAYS, MAX_PROMQL_LENGTH, MetricQueryCount+from products.metrics.backend.models import MetricDailyQueryCount++logger = structlog.get_logger(__name__)++_MAX_METRIC_NAME_LENGTH = MetricDailyQueryCount._meta.get_field("metric_name").max_length or 0+_MAX_METRICS_PER_QUERY = 50+# Snuffle serves the buckets of a stored histogram `<name>` as the virtual series `<name>_bucket`.+_HISTOGRAM_BUCKET_SUFFIX = "_bucket"+++def record_metric_queries(team: Team, metric_names: Iterable[str]) -> None:+ """Count one query for each distinct metric name. A failure is logged and never reaches the query."""+ # Sorted, so that two concurrent upserts lock the rows of a team in the same order and cannot deadlock.+ names = sorted({name for name in metric_names if name and len(name) <= _MAX_METRIC_NAME_LENGTH})[+ :_MAX_METRICS_PER_QUERY+ ]+ if not names:+ return+ # The model is scoped to the root team, so the rows of an environment belong to its parent team.+ team_id = team.parent_team_id or team.pk+ now = timezone.now()+ table = MetricDailyQueryCount._meta.db_table # Trusted: from Django ORM metadata+ values = ", ".join(["(%s, %s, %s, %s, 1, %s)"] * len(names))+ params: list[UUID | int | str | dt.date | dt.datetime] = []+ for name in names:+ params.extend([MetricDailyQueryCount._meta.pk.get_default(), team_id, name, now.date(), now])+ # One statement adds to the row of the day or creates it, so concurrent queries do not lose counts.+ sql = f"""+ INSERT INTO {table} (id, team_id, metric_name, date, query_count, last_queried_at)+ VALUES {values}+ ON CONFLICT (team_id, metric_name, date) DO UPDATE SET+ query_count = {table}.query_count + EXCLUDED.query_count,+ last_queried_at = GREATEST({table}.last_queried_at, EXCLUDED.last_queried_at)+ """+ using = router.db_for_write(MetricDailyQueryCount)+ owns_transaction = not connections[using].in_atomic_block+ try:+ # The savepoint keeps a failed write from breaking a transaction that the caller holds open.+ with transaction.atomic(using=using), connections[using].cursor() as cursor:+ if owns_transaction:+ # Fail fast on a held row. SET LOCAL would outlive a caller's transaction, so only set it in ours.+ cursor.execute("SET LOCAL lock_timeout = '100ms'")+ cursor.execute(sql, params)+ except DatabaseError as error:+ logger.warning("metric_query_count_write_failed", team_id=team_id, metric_count=len(names))+ capture_exception(error)+++def record_promql_query(team: Team, expr: str) -> None:+ """Count one query for each metric that a PromQL expression selects.++ An expression longer than the API accepts does not count, so that tokenizing it stays cheap.+ """+ if len(expr) > MAX_PROMQL_LENGTH:+ return+ # promql_text imports the promql module, which imports this module, so a module-level import is circular.+ from products.metrics.backend.dashboard_import.promql_text import metric_names # noqa: PLC0415++ record_metric_queries(team, (name.removesuffix(_HISTOGRAM_BUCKET_SUFFIX) or name for name in metric_names(expr)))+++def list_metric_query_counts(+ team: Team, *, days: int = DEFAULT_QUERY_COUNT_DAYS, limit: int = 100+) -> list[MetricQueryCount]:+ """The query counts of the last `days` UTC days, today included, with the most queried metric first."""+ since = timezone.now().date() - dt.timedelta(days=days - 1)+ rows = (+ MetricDailyQueryCount.objects.for_team(team.parent_team_id or team.pk, canonical=True)+ .filter(date__gte=since)+ .values("metric_name")+ .annotate(total=Sum("query_count"), last=Max("last_queried_at"))+ .order_by("-total", "metric_name")[:limit]+ )+ return [+ MetricQueryCount(metric_name=row["metric_name"], query_count=row["total"], last_queried_at=row["last"])+ for row in rows+ ]diff --git a/products/metrics/backend/tests/test_api.py b/products/metrics/backend/tests/test_api.pyindex 9d2ab854916d..7144f9364e41 100644--- a/products/metrics/backend/tests/test_api.py+++ b/products/metrics/backend/tests/test_api.py@@ -34,6 +34,7 @@ from products.access_control.backend.models.access_control import AccessControlfrom products.error_tracking.backend.facade.testing import create_issue, create_spike_eventfrom products.metrics.backend.date_range import metrics_query_date_rangefrom products.metrics.backend.presentation.api import _MetricQueryBodySerializer+from products.metrics.backend.query_counts import record_metric_queriesfrom products.metrics.backend.variable_options import (_shared_options,apply_regex,@@ -700,6 +701,27 @@ class TestMetricsErrorSpikesApi(APIBaseTest):assert response.json()["detail"] == "API key missing required scope 'error_tracking:read'"+class TestMetricsQueryCountsApi(APIBaseTest):+ def test_lists_query_counts_with_the_most_queried_metric_first(self) -> None:+ record_metric_queries(self.team, ["cpu"])+ record_metric_queries(self.team, ["http_requests", "cpu"])++ response = self.client.get(f"/api/projects/{self.team.id}/metrics/query_counts/", {"days": 7})++ assert response.status_code == status.HTTP_200_OK+ assert [(row["metric_name"], row["query_count"]) for row in response.json()["results"]] == [+ ("cpu", 2),+ ("http_requests", 1),+ ]++ @parameterized.expand([("zero", "0"), ("over_max", "91"), ("not_an_integer", "abc")])+ def test_invalid_days_is_rejected_with_400(self, _name: str, days: str) -> None:+ response = self.client.get(f"/api/projects/{self.team.id}/metrics/query_counts/", {"days": days})++ assert response.status_code == status.HTTP_400_BAD_REQUEST+ assert response.json()["attr"] == "days"++class TestMetricsFeatureFlagGate(APIBaseTest):@parameterized.expand([diff --git a/products/metrics/backend/tests/test_metric_query_runner.py b/products/metrics/backend/tests/test_metric_query_runner.pyindex 33c571648cfd..806c778a51c3 100644--- a/products/metrics/backend/tests/test_metric_query_runner.py+++ b/products/metrics/backend/tests/test_metric_query_runner.py@@ -33,6 +33,7 @@ from products.metrics.backend.metric_query_runner import ()from products.metrics.backend.metric_samples_query_runner import MetricSamplesQueryRunner, build_metric_query_runnerfrom products.metrics.backend.metrics4_samples import METRICS4_CUTOVER+from products.metrics.backend.query_counts import list_metric_query_countsfrom products.metrics.backend.tests._seeder import seed_metric, truncate_metrics_tables@@ -663,6 +664,21 @@ class TestRunMetricQueryFacade(ClickhouseTestMixin, APIBaseTest):self.assertEqual(series[0].clause, "a")self.assertEqual(sum(p.value for p in series[0].points), 4.0)+ def test_counts_one_query_for_each_metric_it_reads(self):+ run_metric_query(+ team=self.team,+ request=self._request(+ clauses=(+ MetricQueryClause(name="a", metric_name="m1", aggregation=MetricAggregation.SUM),+ MetricQueryClause(name="b", metric_name="m2", aggregation=MetricAggregation.SUM),+ MetricQueryClause(name="c", metric_name="m1", aggregation=MetricAggregation.AVG),+ )+ ),+ )++ counts = list_metric_query_counts(self.team)+ self.assertEqual({count.metric_name: count.query_count for count in counts}, {"m1": 1, "m2": 1})+def test_attaches_ingested_unit_to_series(self):anchor = timezone.now().replace(microsecond=0)seed_metric(@@ -916,6 +932,7 @@ class TestRunMetricQueryInParallel(SimpleTestCase):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.record_metric_queries"),patch("products.metrics.backend.facade.api.connection") as connection,):series = run_metric_query(diff --git a/products/metrics/backend/tests/test_metrics_histogram_query_runner.py b/products/metrics/backend/tests/test_metrics_histogram_query_runner.pyindex dcb7289fdec0..c9524f207b4c 100644--- a/products/metrics/backend/tests/test_metrics_histogram_query_runner.py+++ b/products/metrics/backend/tests/test_metrics_histogram_query_runner.py@@ -23,6 +23,7 @@ from posthog.models.utils import generate_random_token_personal, hash_key_valuefrom products.metrics.backend.hogql_queries.metrics_histogram_query_runner import MetricsHistogramQueryRunnerfrom products.metrics.backend.metric_query_runner import MetricQueryRunner+from products.metrics.backend.query_counts import list_metric_query_countsfrom products.metrics.backend.tests._seeder import seed_metric, truncate_metrics_tables@@ -116,6 +117,9 @@ class TestMetricsHistogramQueryRunner(ClickhouseTestMixin, APIBaseTest):response = self._run()self.assertEqual(response.bounds, [])self.assertEqual(response.counts, [])+ self.assertEqual(+ [(c.metric_name, c.query_count) for c in list_metric_query_counts(self.team)], [("latency", 1)]+ )# The viewer latches the OTel type at pick time and sends it as `metricType` — the# runner must filter on it, or one metric name stored as two types (a histogram anddiff --git a/products/metrics/backend/tests/test_metrics_query_languages.py b/products/metrics/backend/tests/test_metrics_query_languages.pyindex 8a401248e52e..55a32fd38d42 100644--- a/products/metrics/backend/tests/test_metrics_query_languages.py+++ b/products/metrics/backend/tests/test_metrics_query_languages.py@@ -34,6 +34,7 @@ from posthog.shared_link_user import SharedLinkUserfrom products.access_control.backend.facade.user_access_control import UserAccessControlErrorfrom products.metrics.backend.facade.contracts import MetricPointfrom products.metrics.backend.hogql_queries.metrics_query_runner import MetricsQueryRunner+from products.metrics.backend.query_counts import list_metric_query_countsfrom products.metrics.backend.series import rank_and_fill_seriesfrom products.metrics.backend.sql_mode import run_metrics_sql_valuesfrom products.metrics.backend.tests._seeder import seed_metric@@ -443,6 +444,9 @@ class TestMetricsPromQLMode(APIBaseTest):assert [point.value for point in by_job["worker"].points] == [None, 4.0]assert [point.value for point in by_job["api"].points] == [1.5, None]assert by_job["worker"].metricName == "up"+ assert [(count.metric_name, count.query_count) for count in list_metric_query_counts(self.team)] == [+ ("http_requests_total", 1)+ ]@parameterized.expand([diff --git a/products/metrics/backend/tests/test_prometheus_api.py b/products/metrics/backend/tests/test_prometheus_api.pyindex 048f6831bb92..1a7423e70da4 100644--- a/products/metrics/backend/tests/test_prometheus_api.py+++ b/products/metrics/backend/tests/test_prometheus_api.py@@ -1,3 +1,5 @@+from typing import Any+from posthog.test.base import APIBaseTestfrom unittest.mock import MagicMock, patch@@ -10,6 +12,8 @@ from rest_framework import statusfrom posthog.models.personal_api_key import PersonalAPIKeyfrom posthog.models.utils import generate_random_token_personal, hash_key_value+from products.metrics.backend.query_counts import list_metric_query_counts+def _upstream() -> MagicMock:response = MagicMock(spec=requests.Response)@@ -41,6 +45,38 @@ class TestPrometheusQueryApi(APIBaseTest):assert kwargs["headers"]["X-Team-ID"] == str(self.team.pk)assert kwargs["auth"] == ("reader", "secret")+ @parameterized.expand(+ [+ (+ "instant_query",+ "GET",+ "query",+ {"query": "sum(rate(http_requests_total[5m])) / up"},+ ["http_requests_total", "up"],+ ),+ (+ "form_range_query",+ "POST",+ "query_range",+ "query=rate(http_requests_total%5B5m%5D)&step=60",+ ["http_requests_total"],+ ),+ ("series_lookup", "GET", "series", {"match[]": "http_requests_total"}, []),+ ]+ )+ def test_query_requests_count_the_metrics_they_read(+ self, _name: str, method: str, path: str, payload: Any, expected: list[str]+ ):+ if method == "POST":+ response = self.client.post(+ f"{self.base}/{path}", payload, content_type="application/x-www-form-urlencoded"+ )+ else:+ response = self.client.get(f"{self.base}/{path}", payload)++ assert response.status_code == status.HTTP_200_OK+ assert sorted(count.metric_name for count in list_metric_query_counts(self.team)) == sorted(expected)+@parameterized.expand([("label_values", "label/__name__/values"),diff --git a/products/metrics/backend/tests/test_query_counts.py b/products/metrics/backend/tests/test_query_counts.pynew file mode 100644index 000000000000..f245ea35709f--- /dev/null+++ b/products/metrics/backend/tests/test_query_counts.py@@ -0,0 +1,56 @@+import datetime as dt++import time_machine+from posthog.test.base import BaseTest+from unittest.mock import patch++from parameterized import parameterized++from posthog.models import Team++from products.metrics.backend.models import MetricDailyQueryCount+from products.metrics.backend.query_counts import list_metric_query_counts, record_metric_queries, record_promql_query++NOW = dt.datetime(2026, 10, 20, 12, 0, tzinfo=dt.UTC)+++class TestMetricQueryCounts(BaseTest):+ def test_counts_each_metric_once_per_query_inside_the_window(self) -> None:+ other_team = Team.objects.create(organization=self.organization)+ with time_machine.travel(NOW - dt.timedelta(days=40), tick=False):+ record_metric_queries(self.team, ["http_requests"])+ with time_machine.travel(NOW - dt.timedelta(days=2), tick=False):+ record_metric_queries(self.team, ["http_requests", "cpu", "http_requests"])+ with time_machine.travel(NOW, tick=False):+ record_metric_queries(self.team, ["http_requests"])+ record_metric_queries(other_team, ["cpu", "memory"])+ counts = list_metric_query_counts(self.team, days=30, limit=100)++ assert [(count.metric_name, count.query_count, count.last_queried_at) for count in counts] == [+ ("http_requests", 2, NOW),+ ("cpu", 1, NOW - dt.timedelta(days=2)),+ ]++ def test_a_failed_write_does_not_fail_the_query_or_the_next_write(self) -> None:+ with patch.object(MetricDailyQueryCount._meta, "db_table", "metrics_table_that_does_not_exist"):+ record_metric_queries(self.team, ["cpu"])+ record_metric_queries(self.team, ["cpu"])++ assert [(count.metric_name, count.query_count) for count in list_metric_query_counts(self.team)] == [("cpu", 1)]++ @parameterized.expand(+ [+ ("histogram_buckets_count_as_the_stored_histogram", "rate(latency_bucket[5m]) / up", ["latency", "up"]),+ ("expression_over_the_api_limit", "up or " * 2000 + "up", []),+ (+ "names_past_the_per_query_cap",+ " or ".join(f"m{i:02}" for i in range(60)),+ [f"m{i:02}" for i in range(50)],+ ),+ ]+ )+ def test_promql_query_counts_bounded_stored_metric_names(self, _name: str, expr: str, expected: list[str]) -> None:+ record_promql_query(self.team, expr)++ counts = list_metric_query_counts(self.team, limit=1000)+ assert sorted(count.metric_name for count in counts) == expecteddiff --git a/products/metrics/frontend/generated/api.schemas.ts b/products/metrics/frontend/generated/api.schemas.tsindex a4e36ae175dc..b22e3bcfee9a 100644--- a/products/metrics/frontend/generated/api.schemas.ts+++ b/products/metrics/frontend/generated/api.schemas.ts@@ -1072,6 +1072,20 @@ export interface _MetricQueryResponseApi {hint?: string}+export interface _MetricQueryCountApi {+ /** Metric name as it appears in the team's data. */+ metric_name: string+ /** Number of builder and PromQL queries that read the metric in the window. SQL mode queries do not count. */+ query_count: number+ /** When a query last read the metric, ISO 8601. */+ last_queried_at: string+}++export interface _MetricQueryCountsResponseApi {+ /** Metrics that queries read in the window, the most queried first. */+ results: _MetricQueryCountApi[]+}+export interface _MetricSamplesBodyApi {/*** Exact metric name to list raw emissions for (e.g. 'http.server.duration'). Omit to list emissions across all metric names — allowed only with traceId (the trace->metrics pivot).@@ -1581,6 +1595,21 @@ export type MetricsNamesRetrieveParams = {value?: string}+export type MetricsQueryCountsRetrieveParams = {+ /**+ * Number of UTC days to count, today included.+ * @minimum 1+ * @maximum 90+ */+ days?: number+ /**+ * Maximum number of metrics to return.+ * @minimum 1+ * @maximum 1000+ */+ limit?: number+}+export type MetricsValuesRetrieveParams = {/*** Max number of names to return. Defaults to 100; maximum 1000.diff --git a/products/metrics/frontend/generated/api.ts b/products/metrics/frontend/generated/api.tsindex d9a9bb97cc98..4deda2089217 100644--- a/products/metrics/frontend/generated/api.ts+++ b/products/metrics/frontend/generated/api.ts@@ -24,6 +24,7 @@ import type {MetricsDashboardTemplatesPictureRetrieveParams,MetricsErrorSpikesRetrieveParams,MetricsNamesRetrieveParams,+ MetricsQueryCountsRetrieveParams,MetricsSuggestedDashboardApi,MetricsValuesRetrieveParams,PanelQueryCheckRequestApi,@@ -37,6 +38,7 @@ import type {_MetricErrorSpikesResponseApi,_MetricNamesResponseApi,_MetricPickerNamesResponseApi,+ _MetricQueryCountsResponseApi,_MetricQueryRequestApi,_MetricQueryResponseApi,_MetricSamplesRequestApi,@@ -538,6 +540,36 @@ export const metricsQueryCreate = async (})}+export const getMetricsQueryCountsRetrieveUrl = (projectId: string, params?: MetricsQueryCountsRetrieveParams) => {+ const normalizedParams = new URLSearchParams()++ Object.entries(params || {}).forEach(([key, value]) => {+ if (value !== undefined) {+ normalizedParams.append(key, value === null ? 'null' : String(value))+ }+ })++ const stringifiedParams = normalizedParams.toString()++ return stringifiedParams.length > 0+ ? `/api/projects/${projectId}/metrics/query_counts/?${stringifiedParams}`+ : `/api/projects/${projectId}/metrics/query_counts/`+}++/**+ * How often queries read each metric of the team. A metric that no query reads is not in the list.+ */+export const metricsQueryCountsRetrieve = async (+ projectId: string,+ params?: MetricsQueryCountsRetrieveParams,+ options?: RequestInit+): Promise<_MetricQueryCountsResponseApi> => {+ return apiMutator<_MetricQueryCountsResponseApi>(getMetricsQueryCountsRetrieveUrl(projectId, params), {+ ...options,+ method: 'GET',+ })+}+export const getMetricsSamplesCreateUrl = (projectId: string) => {return `/api/projects/${projectId}/metrics/samples/`}diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 1cc6f6e5b025..43e317793473 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -117857,6 +117857,20 @@ export namespace Schemas {dateTo?: string;}+ export interface _MetricQueryCount {+ /** Metric name as it appears in the team's data. */+ metric_name: string;+ /** Number of builder and PromQL queries that read the metric in the window. SQL mode queries do not count. */+ query_count: number;+ /** When a query last read the metric, ISO 8601. */+ last_queried_at: string;+ }++ export interface _MetricQueryCountsResponse {+ /** Metrics that queries read in the window, the most queried first. */+ results: _MetricQueryCount[];+ }+export interface _MetricQueryRequest {/** The metric query to execute. */query: _MetricQueryBody;@@ -130735,6 +130749,21 @@ export namespace Schemas {value?: string;};+ export type MetricsQueryCountsRetrieveParams = {+ /**+ * Number of UTC days to count, today included.+ * @minimum 1+ * @maximum 90+ */+ days?: number;+ /**+ * Maximum number of metrics to return.+ * @minimum 1+ * @maximum 1000+ */+ limit?: number;+ };+export type MetricsValuesRetrieveParams = {/*** Max number of names to return. Defaults to 100; maximum 1000.