Skip to content

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

feat(metrics): 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.yaml
index 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
|RelationshipProposal
diff --git a/posthog/api/snuffle_proxy.py b/posthog/api/snuffle_proxy.py
index 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 None
diff --git a/products/metrics/backend/facade/api.py b/products/metrics/backend/facade/api.py
index 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_qu
from products.metrics.backend.metrics_overview_query_runner import MetricsOverviewQueryRunner
from products.metrics.backend.promql import run_promql_range
from 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_options
from products.metrics.backend.variables import from_dashboard, with_values
@@ -371,6 +377,7 @@ def run_metric_query(*, team: Team, request: MetricQueryRequest) -> list[MetricS
if request.formula is not None
else 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.py
index 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 = 8192
MAX_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.py
index 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, Metr
from products.metrics.backend.facade.enums import AttributeScope, FilterOp
from products.metrics.backend.metric_query_runner import _INTERVAL_LADDER, _QUERY_SETTINGS, _interval_step
from products.metrics.backend.metric_samples_query_runner import build_metric_query_runner
+from products.metrics.backend.query_counts import record_metric_queries
from products.metrics.backend.query_interval import resolve_query_interval
from 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.py
new file mode 100644
index 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.txt
index 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_metricdailyquerycount
diff --git a/products/metrics/backend/models.py b/products/metrics/backend/models.py
index 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.py
index 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.py
index 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.py
index 46e3f2af1e55..fbd571110add 100644
--- a/products/metrics/backend/promql.py
+++ b/products/metrics/backend/promql.py
@@ -16,10 +16,12 @@ from posthog.models import Team
from products.metrics.backend.facade.contracts import MetricPoint, MetricSeries, PromQLQueryError
from products.metrics.backend.metric_query_runner import _align_to_interval, _interval_step, _resolve_interval
+from products.metrics.backend.query_counts import record_promql_query
from 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.py
new file mode 100644
index 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.py
index 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 AccessControl
from products.error_tracking.backend.facade.testing import create_issue, create_spike_event
from products.metrics.backend.date_range import metrics_query_date_range
from products.metrics.backend.presentation.api import _MetricQueryBodySerializer
+from products.metrics.backend.query_counts import record_metric_queries
from 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.py
index 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_runner
from products.metrics.backend.metrics4_samples import METRICS4_CUTOVER
+from products.metrics.backend.query_counts import list_metric_query_counts
from 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.py
index 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_value
from products.metrics.backend.hogql_queries.metrics_histogram_query_runner import MetricsHistogramQueryRunner
from products.metrics.backend.metric_query_runner import MetricQueryRunner
+from products.metrics.backend.query_counts import list_metric_query_counts
from 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 and
diff --git a/products/metrics/backend/tests/test_metrics_query_languages.py b/products/metrics/backend/tests/test_metrics_query_languages.py
index 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 SharedLinkUser
from products.access_control.backend.facade.user_access_control import UserAccessControlError
from products.metrics.backend.facade.contracts import MetricPoint
from products.metrics.backend.hogql_queries.metrics_query_runner import MetricsQueryRunner
+from products.metrics.backend.query_counts import list_metric_query_counts
from products.metrics.backend.series import rank_and_fill_series
from products.metrics.backend.sql_mode import run_metrics_sql_values
from 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.py
index 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 APIBaseTest
from unittest.mock import MagicMock, patch
@@ -10,6 +12,8 @@ from rest_framework import status
from posthog.models.personal_api_key import PersonalAPIKey
from 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.py
new file mode 100644
index 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) == expected
diff --git a/products/metrics/frontend/generated/api.schemas.ts b/products/metrics/frontend/generated/api.schemas.ts
index 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.ts
index 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.ts
index 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.