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.

63.8 KB
Raw Blame
"""DRF views for the alpha metrics product.

Mirrors the shape of `products/logs/backend/api.py` so the two surfaces stay
recognizable.
"""

import re
import datetime as dt
from dataclasses import asdict
from typing import cast
from zoneinfo import ZoneInfo

from django.db import models
from django.utils import timezone

from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import extend_schema, extend_schema_field
from rest_framework import serializers, status, viewsets
from rest_framework.decorators import action
from rest_framework.exceptions import APIException, ParseError, PermissionDenied, Throttled
from rest_framework.request import Request
from rest_framework.response import Response

from posthog.schema import MetricsDashboardVariable, MetricsDashboardVariableSelection, MetricsDashboardVariableSource

from posthog.api.documentation import _FallbackSerializer
from posthog.api.query import CONCURRENCY_LIMIT_RETRY_AFTER_SECONDS, CONCURRENCY_LIMIT_USER_MESSAGE
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.snuffle_proxy import SNUFFLE_API_FEATURE_FLAG
from posthog.clickhouse.client.limit import ConcurrencyLimitExceeded
from posthog.clickhouse.query_tagging import Feature, Product, get_query_tag_value, tag_queries
from posthog.event_usage import report_user_action
from posthog.hogql_queries.query_runner import api_queries_budget_enforcement_enabled, get_api_queries_budget_status
from posthog.models import User
from posthog.permissions import PostHogFeatureFlagPermission, posthog_feature_flag_enabled
from posthog.rate_limit import ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle
from posthog.utils import relative_date_parse

from products.metrics.backend.facade.api import (
    characterize_metric_anomaly,
    check_metric_variable_regex,
    get_metrics_overview,
    list_metric_attribute_keys,
    list_metric_attribute_values,
    list_metric_error_spikes,
    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,
    MetricFilter,
    MetricGroupBy,
    MetricQueryClause,
    MetricQueryRequest,
    MetricSeries,
    PromQLQueryError,
)
from products.metrics.backend.facade.enums import (
    AttributeScope,
    FilterOp,
    MetricAggregation,
    MetricRangeFunction,
    MetricType,
)

__all__ = ["MetricsViewSet"]


class MetricAttributeScope(models.TextChoices):
    RESOURCE = "resource", "resource"
    ATTRIBUTE = "attribute", "attribute"
    AUTO = "auto", "auto"


class MetricQueryAggregation(models.TextChoices):
    NONE = "none", "none"
    SUM = "sum", "sum"
    AVG = "avg", "avg"
    COUNT = "count", "count"
    MIN = "min", "min"
    MAX = "max", "max"
    P95 = "p95", "p95"
    RATE = "rate", "rate"
    INCREASE = "increase", "increase"
    HISTOGRAM_QUANTILE = "histogram_quantile", "histogram_quantile"


class Op(models.TextChoices):
    EQ = "eq", "eq"
    NEQ = "neq", "neq"
    REGEX = "regex", "regex"
    NOT_REGEX = "not_regex", "not_regex"


class _MetricFilterSerializer(serializers.Serializer):
    key = serializers.CharField(
        max_length=255,
        help_text="Attribute name to filter on, without any type-tag suffix (e.g. 'k8s.pod.name', 'env').",
    )
    op = serializers.ChoiceField(
        choices=Op.choices,
        default="eq",
        help_text="Comparison operator. 'regex'/'not_regex' use RE2 syntax. Negative operators also match rows that lack the key entirely, mirroring Prometheus negative matchers.",
    )
    value = serializers.CharField(
        allow_blank=True,
        max_length=1024,
        help_text="Value to compare against. For regex operators this is the pattern.",
    )
    scope = serializers.ChoiceField(
        choices=MetricAttributeScope.choices,
        default="auto",
        help_text="Where the attribute lives: 'resource' = per-target resource attributes (k8s.pod.name, service.version), 'attribute' = per-datapoint attributes (http.method, path), 'auto' = resource first with per-datapoint fallback. Use 'auto' unless you know the exact scope.",
    )


class _MetricGroupBySerializer(serializers.Serializer):
    key = serializers.CharField(
        max_length=255,
        help_text="Attribute name to split series by (e.g. 'k8s.pod.name', 'env').",
    )
    scope = serializers.ChoiceField(
        choices=MetricAttributeScope.choices,
        default="auto",
        help_text="Where the attribute lives; same semantics as filter scope. Use 'auto' unless you know the exact scope.",
    )


class _MetricClauseSerializer(serializers.Serializer):
    name = serializers.CharField(
        max_length=64,
        help_text="Clause name a formula refers to (e.g. 'a').",
    )
    metricName = serializers.CharField(
        max_length=255,
        help_text="Exact metric name this clause queries.",
    )
    metricType = serializers.ChoiceField(
        choices=[t.value for t in MetricType],
        required=False,
        allow_null=True,
        help_text="Constrain the query to one metric type. A name can exist as several types (e.g. a counter and a gauge); without this, rows of every type sharing the name are blended into one aggregate. Get the type from 'metric-names-list'.",
    )
    aggregation = serializers.ChoiceField(
        choices=MetricQueryAggregation.choices,
        default="sum",
        help_text="Aggregation applied per time bucket; same semantics as the top-level aggregation.",
    )
    rangeFunction = serializers.ChoiceField(
        choices=MetricRangeFunction.choices,
        required=False,
        allow_null=True,
        help_text="Counter-aware transform applied to each series before the aggregation: 'rate' (per-second) or 'increase'. Combine with 'none' to get one rate line per series. Do not combine with the 'rate' or 'increase' aggregations.",
    )
    quantile = serializers.FloatField(
        required=False,
        allow_null=True,
        min_value=0.0,
        max_value=1.0,
        help_text="Quantile in (0, 1) for 'histogram_quantile'.",
    )
    filters = _MetricFilterSerializer(
        many=True,
        required=False,
        default=list,
        help_text="Label predicates ANDed together for this clause.",
    )
    groupBy = _MetricGroupBySerializer(
        many=True,
        required=False,
        default=list,
        help_text="Labels to split this clause into separate series by.",
    )


class MetricQueryInterval(models.TextChoices):
    SECOND_15 = "second_15", "second_15"
    SECOND_30 = "second_30", "second_30"
    MINUTE = "minute", "minute"
    MINUTE_5 = "minute_5", "minute_5"
    MINUTE_15 = "minute_15", "minute_15"
    MINUTE_30 = "minute_30", "minute_30"
    HOUR = "hour", "hour"
    HOUR_6 = "hour_6", "hour_6"
    DAY = "day", "day"
    WEEK = "week", "week"


# ASCII digits with a length cap: `\d` also matches other scripts, which makes the parser backtrack quadratically.
_RELATIVE_DATE_RE = re.compile(r"^-[0-9]{1,6}[hdwmy]$")
_DEFAULT_QUERY_LOOKBACK = dt.timedelta(hours=24)


class _PromQLBackendUnavailable(APIException):
    status_code = 503
    default_code = "promql_backend_unavailable"
    default_detail = "The PromQL query backend failed. Try again later."


_PROMQL_EXCLUDED_FIELDS = ("metricType", "aggregation", "rangeFunction", "quantile", "filters", "groupBy", "formula")


@extend_schema_field(OpenApiTypes.STR)
class _RelativeOrIsoDateTimeField(serializers.DateTimeField):
    # Relative offsets stay strings so the body serializer resolves both bounds against one "now";
    # two separate clock reads would push a maximum-span lookback past the runner's limit.
    def to_internal_value(self, value: dt.datetime | str) -> dt.datetime | str:  # type: ignore[override]
        if isinstance(value, str) and _RELATIVE_DATE_RE.match(value.strip()):
            return value.strip()
        return super().to_internal_value(value)


def _resolve_query_bound(value: dt.datetime | str | None, *, now: dt.datetime, field: str) -> dt.datetime | None:
    if not isinstance(value, str):
        return value
    try:
        return relative_date_parse(value, ZoneInfo("UTC"), now=now)
    except (ValueError, OverflowError):
        raise serializers.ValidationError({field: f"'{value}' is too far back to be a valid date."})


class _MetricQueryBodySerializer(serializers.Serializer):
    metricName = serializers.CharField(
        max_length=255,
        required=False,
        help_text="Exact metric name to query (e.g. 'http.server.duration'). Single-clause shorthand — mutually exclusive with 'clauses'.",
    )
    metricType = serializers.ChoiceField(
        choices=[t.value for t in MetricType],
        required=False,
        allow_null=True,
        help_text="Constrain the query to one metric type. A name can exist as several types (e.g. a counter and a gauge); without this, rows of every type sharing the name are blended into one aggregate. Get the type from 'metric-names-list'.",
    )
    aggregation = serializers.ChoiceField(
        choices=MetricQueryAggregation.choices,
        required=False,
        help_text="Defaults to 'sum'. Aggregation applied per time bucket, always across series rather than across raw samples. 'sum', 'avg', 'min', 'max' and 'p95' reduce each series to its last sample in the bucket and then combine those, so the result does not scale with the scrape rate; 'count' is the number of series that reported. 'rate' (per-second) and 'increase' are counter-aware: per-series deltas with Prometheus counter-reset handling, temporality-aware (delta-temporality samples count as-is). 'histogram_quantile' interpolates from OTel histogram buckets and requires 'quantile'. 'none' skips the aggregation and returns one series per label set, at most 100, using each series' last sample per bucket; it cannot be combined with 'groupBy'.",
    )
    rangeFunction = serializers.ChoiceField(
        choices=MetricRangeFunction.choices,
        required=False,
        allow_null=True,
        help_text="Counter-aware transform applied to each series before the aggregation: 'rate' (per-second) or 'increase'. Combine with 'none' to get one rate line per series. Do not combine with the 'rate' or 'increase' aggregations.",
    )
    quantile = serializers.FloatField(
        required=False,
        allow_null=True,
        min_value=0.0,
        max_value=1.0,
        help_text="Quantile in (0, 1) for 'histogram_quantile' (e.g. 0.95). Ignored for other aggregations.",
    )
    filters = _MetricFilterSerializer(
        many=True,
        required=False,
        default=list,
        help_text="Label predicates ANDed together. Rows must satisfy every filter.",
    )
    groupBy = _MetricGroupBySerializer(
        many=True,
        required=False,
        default=list,
        help_text="Labels to split the result into separate series by. Series share one time grid and are capped at the 100 largest.",
    )
    interval = serializers.ChoiceField(
        choices=MetricQueryInterval.choices,
        required=False,
        allow_null=True,
        help_text="Bucket size for the shared time grid. Omit to auto-pick (~60 buckets across the range).",
    )
    # mypy can't see DRF's many_init routing max_length to the ListSerializer
    clauses = _MetricClauseSerializer(  # type: ignore[call-arg]
        many=True,
        required=False,
        max_length=MAX_CLAUSES_PER_QUERY,
        help_text=f"Full multi-clause form: each clause is an independent metric selection sharing the request's time grid (maximum {MAX_CLAUSES_PER_QUERY}). Mutually exclusive with 'metricName'.",
    )
    formula = serializers.CharField(
        required=False,
        allow_null=True,
        max_length=512,
        help_text="Arithmetic over clause names evaluated server-side per grid point, e.g. '(a - b) / a'. Supports + - * / and parentheses; division by zero yields 0. When set, only the formula result series are returned.",
    )
    promql = serializers.CharField(
        required=False,
        allow_null=True,
        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(
        required=False,
        help_text="Lower bound (inclusive) for the query range. ISO 8601, or a relative offset back from now such as '-1h', '-7d', '-2w', '-1m' (months). Defaults to 24 hours before dateTo.",
    )
    dateTo = _RelativeOrIsoDateTimeField(
        required=False,
        help_text="Upper bound (exclusive) for the query range. ISO 8601 or a relative offset like dateFrom. Defaults to now if omitted.",
    )

    def validate(self, attrs: dict) -> dict:
        now = timezone.now()
        date_to = _resolve_query_bound(attrs.get("dateTo"), now=now, field="dateTo") or now
        date_from = _resolve_query_bound(attrs.get("dateFrom"), now=now, field="dateFrom")
        if date_from is None:
            try:
                date_from = date_to - _DEFAULT_QUERY_LOOKBACK
            except OverflowError:
                raise serializers.ValidationError({"dateTo": "Too early to leave 'dateFrom' unset."})
        attrs["dateFrom"] = date_from
        attrs["dateTo"] = date_to
        has_single = bool(attrs.get("metricName"))
        has_clauses = bool(attrs.get("clauses"))
        has_promql = bool((attrs.get("promql") or "").strip())
        if [has_single, has_clauses, has_promql].count(True) != 1:
            raise serializers.ValidationError("Provide exactly one of 'metricName', 'clauses' or 'promql'.")
        if has_promql:
            if set_fields := [field for field in _PROMQL_EXCLUDED_FIELDS if attrs.get(field)]:
                raise serializers.ValidationError(
                    f"'promql' cannot be combined with {', '.join(repr(f) for f in set_fields)}. "
                    "Put selectors, grouping and functions in the PromQL expression."
                )
            return attrs
        attrs.setdefault("aggregation", "sum")
        if attrs.get("formula") and not has_clauses:
            raise serializers.ValidationError("'formula' requires 'clauses'.")
        if has_clauses and attrs.get("metricType"):
            raise serializers.ValidationError(
                "'metricType' applies to the single-clause shorthand; set it per clause instead."
            )
        return attrs


class _MetricQueryRequestSerializer(serializers.Serializer):
    query = _MetricQueryBodySerializer(help_text="The metric query to execute.")


def _build_clause(data: dict, *, name: str) -> MetricQueryClause:
    """Validated wire clause (or single-clause shorthand body) → contract.

    The wire aggregation "p95" is contract QUANTILE(0.95)."""
    aggregation_raw: str = data["aggregation"]
    quantile: float | None = None
    if aggregation_raw == "p95":
        aggregation, quantile = MetricAggregation.QUANTILE, 0.95
    elif aggregation_raw == "histogram_quantile":
        aggregation, quantile = MetricAggregation.HISTOGRAM_QUANTILE, data.get("quantile")
    else:
        aggregation = MetricAggregation(aggregation_raw)

    metric_type_raw = data.get("metricType")
    range_function_raw = data.get("rangeFunction")
    return MetricQueryClause(
        name=name,
        metric_name=data["metricName"],
        aggregation=aggregation,
        quantile=quantile,
        metric_type=MetricType(metric_type_raw) if metric_type_raw else None,
        range_function=MetricRangeFunction(range_function_raw) if range_function_raw else None,
        filters=tuple(
            MetricFilter(key=f["key"], op=FilterOp(f["op"]), value=f["value"], scope=AttributeScope(f["scope"]))
            for f in data.get("filters") or []
        ),
        group_by=tuple(
            MetricGroupBy(key=g["key"], scope=AttributeScope(g["scope"])) for g in data.get("groupBy") or []
        ),
    )


class _MetricQueryPointSerializer(serializers.Serializer):
    time = serializers.CharField(help_text="Bucket start as ISO 8601 timestamp.")
    value = serializers.FloatField(
        allow_null=True,
        help_text="Aggregated value for the bucket. Null when the aggregate isn't representable (e.g. float overflow) — render as a gap.",
    )


class _MetricSeriesSerializer(serializers.Serializer):
    labels = serializers.DictField(
        child=serializers.CharField(),
        help_text="Label values identifying this series. Empty for an ungrouped query.",
    )
    points = _MetricQueryPointSerializer(many=True, help_text="Time-bucketed points, ordered by time ascending.")
    metric_name = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Metric the series was computed from. Null for formula results.",
    )
    clause = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Name of the query clause that produced this series.",
    )
    unit = serializers.CharField(
        required=False,
        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):
    results = _MetricSeriesSerializer(
        many=True,
        help_text="One series per (clause, label-set). A single ungrouped query returns exactly one series with empty labels.",
    )
    hint = serializers.CharField(
        required=False,
        help_text="Set only when the query returned no points: what to check before querying again.",
    )


_NO_SERIES_HINT = (
    "The query returned no points, and the same query will return the same result. Look up the exact metric "
    "name and type with metric-names-list, remove or loosen filters, or widen the time range. With a formula, "
    "check that the clauses group by the same labels: only series with matching labels combine."
)


def _series_response(series: list[MetricSeries]) -> Response:
    response_data: dict = {"results": [asdict(s) for s in series]}
    if not any(s.points for s in series):
        response_data["hint"] = _NO_SERIES_HINT
    return Response(response_data, status=status.HTTP_200_OK)


class _MetricAnomalyBodySerializer(serializers.Serializer):
    metricName = serializers.CharField(
        max_length=255,
        help_text="Exact metric name to characterize (e.g. 'metrics_rate_limiter_message_lag_seconds').",
    )
    anomalyFrom = serializers.DateTimeField(
        help_text="Start of the suspicious window (inclusive). ISO 8601 — e.g. when the alert fired or the graph started looking wrong.",
    )
    anomalyTo = serializers.DateTimeField(
        required=False,
        help_text="End of the suspicious window (exclusive). Defaults to now.",
    )
    baselineFrom = serializers.DateTimeField(
        required=False,
        help_text="Start of the healthy comparison window. Defaults to one anomaly-window-length before baselineTo.",
    )
    baselineTo = serializers.DateTimeField(
        required=False,
        help_text="End of the healthy comparison window. Defaults to anomalyFrom. Must not extend past anomalyFrom.",
    )
    aggregation = serializers.ChoiceField(
        choices=["sum", "avg", "count", "min", "max", "p95", "rate", "increase", "histogram_quantile"],
        required=False,
        allow_null=True,
        help_text="Aggregation to characterize. Omit to auto-pick from the metric's OTel type (counter -> rate, gauge -> avg, histogram -> histogram_quantile 0.95).",
    )
    quantile = serializers.FloatField(
        required=False,
        allow_null=True,
        min_value=0.0,
        max_value=1.0,
        help_text="Quantile for histogram_quantile. Defaults to 0.95.",
    )
    filters = _MetricFilterSerializer(
        many=True,
        required=False,
        default=list,
        help_text="Label predicates narrowing which series are characterized.",
    )
    candidateKeys = serializers.ListField(
        child=serializers.CharField(max_length=255),
        required=False,
        help_text="Label keys to drill into when finding which label values moved. Omit to auto-discover the most common keys on this metric (plus service_name). Max 4 are used.",
    )


class _MetricAnomalyRequestSerializer(serializers.Serializer):
    query = _MetricAnomalyBodySerializer(help_text="The anomaly characterization to run.")


class _MetricAnomalyDimensionSerializer(serializers.Serializer):
    key = serializers.CharField(help_text="Label key that was drilled into.")
    # the name shadows rest_framework Field.label as far as mypy can tell;
    # DRF itself handles declared fields named `label` fine
    label = serializers.CharField(help_text="Label value this row describes.")  # type: ignore[assignment]
    baseline_value = serializers.FloatField(help_text="Mean value over the baseline window for this label value.")
    anomaly_value = serializers.FloatField(help_text="Mean value over the anomaly window for this label value.")
    change_ratio = serializers.FloatField(
        help_text="anomaly_value / baseline_value. A zero baseline yields the anomaly value itself (new traffic)."
    )


class MetricAnomalyDirection(models.TextChoices):
    UP = "up", "up"
    DOWN = "down", "down"
    FLAT = "flat", "flat"


class _MetricAnomalyReportSerializer(serializers.Serializer):
    metric_name = serializers.CharField(help_text="Metric that was characterized.")
    aggregation = serializers.CharField(help_text="Aggregation used (auto-picked when not specified).")
    interval = serializers.CharField(help_text="Bucket size of the analysis grid.")
    baseline_from = serializers.CharField(help_text="Baseline window start, ISO 8601.")
    baseline_to = serializers.CharField(help_text="Baseline window end, ISO 8601.")
    anomaly_from = serializers.CharField(help_text="Anomaly window start, ISO 8601.")
    anomaly_to = serializers.CharField(help_text="Anomaly window end, ISO 8601.")
    baseline_mean = serializers.FloatField(help_text="Mean over the baseline window.")
    baseline_stddev = serializers.FloatField(help_text="Population stddev over the baseline window.")
    anomaly_mean = serializers.FloatField(help_text="Mean over the anomaly window.")
    anomaly_peak = serializers.FloatField(help_text="Maximum bucket value in the anomaly window.")
    change_ratio = serializers.FloatField(
        help_text="anomaly_mean / baseline_mean. A zero baseline yields anomaly_mean itself."
    )
    direction = serializers.ChoiceField(
        choices=MetricAnomalyDirection.choices, help_text="Which way the metric moved versus the baseline."
    )
    onset_time = serializers.CharField(
        allow_null=True,
        help_text="First bucket clearly outside the baseline range (3 stddevs or 50% relative change), or null if no clear onset.",
    )
    top_movers = _MetricAnomalyDimensionSerializer(
        many=True,
        help_text="Label values whose behavior changed the most between windows, largest change first. Empty when nothing moved or the metric has no labels.",
    )
    series = _MetricSeriesSerializer(
        help_text="The metric across baseline + anomaly windows on one grid, for plotting or further inspection."
    )


class _HasMetricsResponseSerializer(serializers.Serializer):
    hasMetrics = serializers.BooleanField(help_text="Whether the team has ingested any metrics.")


class _MetricsOverviewServiceSerializer(serializers.Serializer):
    service_name = serializers.CharField(help_text="Service that reported metrics inside the window.")
    metric_names = serializers.IntegerField(help_text="Distinct metric names this service reported in the window.")
    series = serializers.IntegerField(
        help_text="Distinct series (metric + label-set combinations) this service reported in the window."
    )
    last_seen = serializers.CharField(help_text="When this service's newest datapoint arrived, ISO 8601.")


class _MetricsOverviewResponseSerializer(serializers.Serializer):
    last_seen = serializers.CharField(
        allow_null=True,
        help_text="When the newest datapoint arrived across all series, ISO 8601. Unlike the counts this ignores the window, so it still answers 'when did ingestion stop'. Null when nothing was ever ingested.",
    )
    metric_names = serializers.IntegerField(help_text="Distinct metric names reported inside the window.")
    series = serializers.IntegerField(
        help_text="Distinct series (metric + label-set combinations) reported inside the window."
    )
    lookback_seconds = serializers.IntegerField(
        help_text="Length of the rollup window in seconds, so consumers can label the counts."
    )
    services = _MetricsOverviewServiceSerializer(
        many=True,
        help_text="Per-service rollup for the window, largest series count first. Capped at the 500 largest.",
    )


class _MetricValuesParamsSerializer(serializers.Serializer):
    value = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=255,
        help_text="Substring filter (case-insensitive) applied to metric names.",
    )
    limit = serializers.IntegerField(
        required=False,
        default=100,
        min_value=1,
        max_value=1000,
        help_text="Max number of names to return. Defaults to 100; maximum 1000.",
    )
    service = serializers.CharField(
        required=False,
        allow_blank=True,
        default=None,
        max_length=1024,
        help_text=(
            "Comma-separated services to narrow the list to, e.g. `service=web,worker`. "
            "Omit for every service. Send it empty to select only series whose sender "
            "did not set `service.name`. A service name containing a comma cannot be "
            "selected."
        ),
    )

    def validate_service(self, value: str | None) -> list[str]:
        # Absent and empty mean different things, which is why the default is None
        # rather than "": omitting the param leaves the picker unscoped, while
        # sending it empty scopes to the senders that set no service name.
        if value is None:
            return []
        return [service.strip() for service in value.split(",")]


class _MetricCatalogValuesParamsSerializer(_MetricValuesParamsSerializer):
    names = serializers.ListField(
        child=serializers.CharField(max_length=255, trim_whitespace=False),
        allow_empty=False,
        min_length=1,
        max_length=MAX_SPARKLINE_BATCH_SIZE,
        help_text="Exact metric names to load as a batch. Overrides value and limit.",
    )


class _MetricNameSerializer(serializers.Serializer):
    name = serializers.CharField(help_text="Metric name as it appears in the team's data.")
    metric_type = serializers.CharField(
        help_text="OTel metric type (gauge, sum, histogram, summary, exponential_histogram)."
    )
    unit = serializers.CharField(
        required=False, allow_blank=True, help_text="Unit of the metric value, if any (e.g. 'ms', 'By')."
    )
    last_seen = serializers.DateTimeField(
        required=False, allow_null=True, help_text="When the newest datapoint for this metric arrived, ISO 8601."
    )
    sparkline = serializers.ListField(
        child=serializers.FloatField(),
        required=False,
        help_text="A small downsampled series of the metric's recent shape, for a sparkline.",
    )


class _MetricPickerNameSerializer(serializers.Serializer):
    name = serializers.CharField(help_text="Metric name as it appears in the team's data.")
    metric_type = serializers.CharField(
        help_text="OTel metric type (gauge, sum, histogram, summary, exponential_histogram)."
    )


class _MetricNamesResponseSerializer(serializers.Serializer):
    results = _MetricNameSerializer(many=True, help_text="Distinct metric names ordered by recent activity.")


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,
        allow_blank=True,
        default="",
        max_length=255,
        help_text="Exact metric name to limit attribute keys to. Omit to list keys across all metrics.",
    )
    search = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=255,
        help_text="Substring filter (case-insensitive) applied to attribute keys.",
    )
    dateFrom = serializers.DateTimeField(
        required=False,
        allow_null=True,
        default=None,
        help_text="Lower bound (inclusive) of the window keys are suggested from. ISO 8601. Defaults to 24 hours ago.",
    )
    dateTo = serializers.DateTimeField(
        required=False,
        allow_null=True,
        default=None,
        help_text="Upper bound (exclusive) of the window. ISO 8601. Defaults to now.",
    )
    limit = serializers.IntegerField(
        required=False,
        default=100,
        min_value=1,
        max_value=1000,
        help_text="Max number of keys to return. Defaults to 100; maximum 1000.",
    )


class _MetricAttributeValuesParamsSerializer(serializers.Serializer):
    key = serializers.CharField(
        max_length=255,
        help_text="Attribute key to list values for (e.g. 'env'). 'service_name'/'service.name' list service names.",
    )
    metricName = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=255,
        help_text="Exact metric name to limit values to. Omit to list values across all metrics.",
    )
    value = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=1024,
        help_text="Substring filter (case-insensitive) applied to values. Named 'value' to match the property-values autocomplete convention.",
    )
    dateFrom = serializers.DateTimeField(
        required=False,
        allow_null=True,
        default=None,
        help_text="Lower bound (inclusive) of the window values are suggested from. ISO 8601. Defaults to 24 hours ago.",
    )
    dateTo = serializers.DateTimeField(
        required=False,
        allow_null=True,
        default=None,
        help_text="Upper bound (exclusive) of the window. ISO 8601. Defaults to now.",
    )
    limit = serializers.IntegerField(
        required=False,
        default=100,
        min_value=1,
        max_value=1000,
        help_text="Max number of values to return. Defaults to 100; maximum 1000.",
    )


class _MetricAttributeKeySerializer(serializers.Serializer):
    name = serializers.CharField(
        help_text="Attribute key as it appears on the team's metrics (e.g. 'env', 'k8s.pod.name')."
    )
    value_count = serializers.IntegerField(help_text="Number of distinct values for this attribute in recent data.")


class _MetricAttributeKeysResponseSerializer(serializers.Serializer):
    results = _MetricAttributeKeySerializer(
        many=True,
        help_text="Distinct attribute keys (datapoint and resource attributes merged), ordered by distinct value count descending.",
    )
    count = serializers.IntegerField(help_text="Number of keys returned.")


class _MetricAttributeValueSerializer(serializers.Serializer):
    id = serializers.CharField(help_text="The attribute value (same as name; kept for picker compatibility).")
    name = serializers.CharField(help_text="The attribute value.")
    count = serializers.IntegerField(help_text="Number of data points observed with this value in the window.")


class _MetricAttributeValuesResponseSerializer(serializers.Serializer):
    results = _MetricAttributeValueSerializer(
        many=True, help_text="Observed values for the requested key, most frequent first."
    )


class MetricVariableSource(models.TextChoices):
    CUSTOM = "custom", "custom"
    PROMQL = "promql", "promql"
    SQL = "sql", "sql"
    TEXTBOX = "textbox", "textbox"


class _MetricVariableSelectionSerializer(serializers.Serializer):
    name = serializers.RegexField(
        r"^[A-Za-z_][A-Za-z0-9_]*$",
        max_length=128,
        help_text="Variable name. Queries refer to it as `$name`.",
    )
    values = serializers.ListField(
        child=serializers.CharField(max_length=1024, allow_blank=True, trim_whitespace=False),
        max_length=1000,
        help_text="The selected values. When `all` is true, the options that All stands for.",
    )
    all = serializers.BooleanField(required=False, default=False, help_text="True when the variable is set to All.")
    allValue = serializers.CharField(
        required=False,
        allow_null=True,
        allow_blank=True,
        default=None,
        max_length=1024,
        trim_whitespace=False,
        help_text="The text that All puts in a PromQL query. `.*` when it is empty.",
    )


class _MetricVariableOptionsRequestSerializer(serializers.Serializer):
    source = serializers.ChoiceField(  # type: ignore[assignment]
        choices=MetricVariableSource.choices,
        help_text="Where the options come from: a static list, a PromQL query, a SQL query, or free text.",
    )
    query = serializers.CharField(
        required=False,
        allow_null=True,
        allow_blank=True,
        default=None,
        max_length=10_000,
        help_text=(
            "The options query when `source` is `promql` or `sql`. It can refer to other variables as `$name`. "
            "PromQL supports label_values(label), label_values(selector, label), label_names(), metrics(regex) "
            "and query_result(expr). SQL returns the options in its first column."
        ),
    )
    customValues = serializers.ListField(
        child=serializers.CharField(max_length=1024, allow_blank=True, trim_whitespace=False),
        required=False,
        allow_null=True,
        default=None,
        max_length=1000,
        help_text="The options when `source` is `custom`.",
    )
    regex = serializers.CharField(
        required=False,
        allow_null=True,
        allow_blank=True,
        default=None,
        max_length=1024,
        trim_whitespace=False,
        help_text=(
            "A regex that filters the options of a query, as `pattern` or `/pattern/flags`. "
            "With a capture group, each option is its first group. An invalid regex is rejected before any query runs."
        ),
    )
    variables = _MetricVariableSelectionSerializer(
        many=True,
        required=False,
        default=list,
        help_text="The current selection of the other dashboard variables that the query can refer to.",
    )
    dateFrom = serializers.CharField(
        required=False,
        allow_null=True,
        default=None,
        max_length=64,
        help_text=(
            "Start of the window that options come from, as in a dashboard date filter: "
            "ISO 8601 or a relative date such as '-7d'. Defaults to 24 hours ago."
        ),
    )
    dateTo = serializers.CharField(
        required=False,
        allow_null=True,
        default=None,
        max_length=64,
        help_text="End of the window that options come from, in the same format as dateFrom. Defaults to now.",
    )

    def validate_regex(self, value: str | None) -> str | None:
        try:
            check_metric_variable_regex(value)
        except ValueError as exc:
            raise serializers.ValidationError(str(exc)) from exc
        return value


class _MetricVariableOptionsResponseSerializer(serializers.Serializer):
    results = serializers.ListField(
        child=serializers.CharField(), help_text="The options of the variable, at most 1,000."
    )


class _MetricSamplesBodySerializer(serializers.Serializer):
    metricName = serializers.CharField(
        required=False,
        allow_blank=True,
        max_length=255,
        help_text=(
            "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)."
        ),
    )
    dateFrom = serializers.DateTimeField(
        help_text="Lower bound (inclusive) for the sample window. ISO 8601.",
    )
    dateTo = serializers.DateTimeField(
        required=False,
        help_text="Upper bound (exclusive) for the sample window. Defaults to now if omitted.",
    )
    traceId = serializers.CharField(
        required=False,
        allow_blank=True,
        max_length=255,
        help_text="Restrict to emissions on this trace (hex trace id, as the tracing product uses) — the reverse metric->trace pivot. Omit for all traces.",
    )
    spanId = serializers.CharField(
        required=False,
        allow_blank=True,
        max_length=255,
        help_text="Restrict to emissions recorded on this span (hex span id). Requires traceId, since a span id is only unique within its trace.",
    )
    metricType = serializers.ChoiceField(
        choices=[t.value for t in MetricType],
        required=False,
        allow_null=True,
        help_text="Constrain the emissions to one metric type. A name can exist as several types (e.g. a counter and a gauge); without this, emissions of every type sharing the name are listed together. Pass the same value used for the chart so both describe the same series.",
    )
    filters = _MetricFilterSerializer(
        many=True,
        required=False,
        default=list,
        help_text="Label predicates ANDed together, matched against each emission's series. Pass the same filters used for the chart so the emissions listed are the ones behind it.",
    )
    limit = serializers.IntegerField(
        required=False,
        default=100,
        min_value=1,
        max_value=1000,
        help_text="Max emissions to return, newest first. Defaults to 100, capped at 1000.",
    )

    def validate(self, attrs: dict) -> dict:
        if not attrs.get("metricName") and not attrs.get("traceId"):
            raise serializers.ValidationError("metricName or traceId is required.")
        if attrs.get("spanId") and not attrs.get("traceId"):
            raise serializers.ValidationError("spanId requires traceId.")
        return attrs


class _MetricSamplesRequestSerializer(serializers.Serializer):
    query = _MetricSamplesBodySerializer(help_text="The raw-emissions query to execute.")


class _MetricEventSampleSerializer(serializers.Serializer):
    timestamp = serializers.CharField(help_text="When the metric was emitted, ISO 8601.")
    metric_name = serializers.CharField(help_text="Metric this emission belongs to.")
    metric_type = serializers.CharField(
        help_text="OTel metric type: gauge, sum, histogram, summary, or exponential_histogram."
    )
    value = serializers.FloatField(
        help_text="The emitted value. For histogram/summary points this is the distribution sum; pair with count."
    )
    count = serializers.IntegerField(
        help_text="Observations behind this point: 1 for gauges/counters, the distribution count for histograms/summaries."
    )
    unit = serializers.CharField(help_text="Unit of the value, if any.")
    aggregation_temporality = serializers.CharField(
        help_text="For counters: 'delta' or 'cumulative' (decides whether rate() must diff). Empty for gauges."
    )
    is_monotonic = serializers.BooleanField(help_text="True for monotonically increasing counters.")
    service_name = serializers.CharField(help_text="Service that emitted the metric.")
    trace_id = serializers.CharField(
        help_text="Trace this emission belongs to (hex, same form the tracing product uses); empty if none. Use it to pivot to the trace.",
    )
    span_id = serializers.CharField(help_text="Span this emission belongs to (hex); empty if none.")
    attributes = serializers.DictField(
        child=serializers.CharField(),
        help_text="Per-emission attributes (high-cardinality labels on the data point).",
    )
    resource_attributes = serializers.DictField(
        child=serializers.CharField(),
        help_text="Attributes of the resource (host, pod, service version) that emitted the metric.",
    )


class _MetricSamplesResponseSerializer(serializers.Serializer):
    results = _MetricEventSampleSerializer(
        many=True,
        help_text="Raw emissions ordered by timestamp descending.",
    )


class _MetricErrorSpikesParamsSerializer(serializers.Serializer):
    dateFrom = serializers.DateTimeField(
        help_text="Lower bound (inclusive) for the spike window. ISO 8601.",
    )
    dateTo = serializers.DateTimeField(
        required=False,
        help_text="Upper bound (exclusive) for the spike window. Defaults to now if omitted.",
    )


class _MetricErrorSpikeSerializer(serializers.Serializer):
    detected_at = serializers.CharField(help_text="When the error spike was detected, ISO 8601.")
    issue_id = serializers.CharField(help_text="Error Tracking issue that spiked.")
    issue_name = serializers.CharField(
        allow_null=True,
        help_text="Issue name, if one is set.",
    )


class _MetricErrorSpikesResponseSerializer(serializers.Serializer):
    results = _MetricErrorSpikeSerializer(
        many=True,
        help_text=(
            "Error Tracking issue spikes detected in the window, newest first. Team-wide: not yet "
            "scoped to a specific metric's service."
        ),
    )


@extend_schema(tags=["metrics"])
class MetricsViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
    scope_object = "metrics"
    serializer_class = _FallbackSerializer
    # Metrics is in private alpha: gate the API behind the `metrics` flag so only
    # PostHog and directly-added teams can reach it. Added to the mixin's default
    # permissions (team/org/access-control), not replacing them.
    posthog_feature_flag = METRICS_FEATURE_FLAG
    permission_classes = [PostHogFeatureFlagPermission]

    @extend_schema(responses={200: _HasMetricsResponseSerializer})
    @action(detail=False, methods=["GET"], required_scopes=["metrics:read"])
    def has_metrics(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)
        has_metrics = team_has_metrics(self.team)

        report_user_action(
            request.user,
            "metrics has_metrics checked",
            {"has_metrics": has_metrics},
            team=self.team,
            request=request,
        )

        return Response({"hasMetrics": has_metrics}, status=status.HTTP_200_OK)

    @extend_schema(responses={200: _MetricsOverviewResponseSerializer})
    @action(
        detail=False,
        methods=["GET"],
        required_scopes=["metrics:read"],
        throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
    )
    def overview(self, request: Request, *args, **kwargs) -> Response:
        """Ingestion rollup for the overview page: freshness of the newest
        datapoint plus per-service metric/series counts over the last day."""
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        overview = get_metrics_overview(team=self.team)

        report_user_action(
            request.user,
            "metrics overview viewed",
            {
                "service_count": len(overview.services),
                "has_ingested": overview.last_seen is not None,
            },
            team=self.team,
            request=request,
        )

        return Response(asdict(overview), status=status.HTTP_200_OK)

    @extend_schema(
        methods=["GET"],
        parameters=[_MetricValuesParamsSerializer],
        responses={200: _MetricNamesResponseSerializer},
    )
    @extend_schema(
        methods=["POST"],
        request=_MetricCatalogValuesParamsSerializer,
        responses={200: _MetricNamesResponseSerializer},
    )
    @action(
        detail=False,
        methods=["GET", "POST"],
        required_scopes=["metrics:read"],
        throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
    )
    def values(self, request: Request, *args, **kwargs) -> Response:
        """Distinct metric names for the team. Backs the catalog UI."""
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        params = (
            _MetricCatalogValuesParamsSerializer(data=request.data)
            if request.method == "POST"
            else _MetricValuesParamsSerializer(data=request.query_params)
        )
        params.is_valid(raise_exception=True)

        try:
            results = list_metric_names(
                team=self.team,
                search=params.validated_data["value"],
                limit=params.validated_data["limit"],
                services=params.validated_data["service"],
                names=params.validated_data.get("names", []),
            )
        except ValueError as exc:
            raise ParseError(str(exc))

        return Response({"results": results}, status=status.HTTP_200_OK)

    @extend_schema(
        parameters=[_MetricValuesParamsSerializer],
        responses={200: _MetricPickerNamesResponseSerializer},
    )
    @action(
        detail=False,
        methods=["GET"],
        required_scopes=["metrics:read"],
        throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
    )
    def names(self, request: Request, *args, **kwargs) -> Response:
        """Distinct metric names for the viewer picker, without sparklines or caching."""
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        params = _MetricValuesParamsSerializer(data=request.query_params)
        params.is_valid(raise_exception=True)

        try:
            results = list_metric_picker_names(
                team=self.team,
                search=params.validated_data["value"],
                limit=params.validated_data["limit"],
                services=params.validated_data["service"],
            )
        except ValueError as exc:
            raise ParseError(str(exc))

        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},
    )
    @action(
        detail=False,
        methods=["GET"],
        required_scopes=["metrics:read"],
        throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
    )
    def attributes(self, request: Request, *args, **kwargs) -> Response:
        """Attribute keys ordered by distinct series count, from highest to
        lowest. `metricName` limits choices to one metric."""
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        params = _MetricAttributeKeysParamsSerializer(data=request.query_params)
        params.is_valid(raise_exception=True)

        try:
            results = list_metric_attribute_keys(
                team=self.team,
                metric_name=params.validated_data["metricName"],
                search=params.validated_data["search"],
                date_from=params.validated_data["dateFrom"],
                date_to=params.validated_data["dateTo"],
                limit=params.validated_data["limit"],
            )
        except ValueError as exc:
            raise ParseError(str(exc))

        return Response({"results": results, "count": len(results)}, status=status.HTTP_200_OK)

    @extend_schema(
        parameters=[_MetricAttributeValuesParamsSerializer],
        responses={200: _MetricAttributeValuesResponseSerializer},
    )
    @action(
        detail=False,
        methods=["GET"],
        required_scopes=["metrics:read"],
        throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
    )
    def attribute_values(self, request: Request, *args, **kwargs) -> Response:
        """Observed values for one metric attribute key, most frequent first.
        Backs the filter bar's value autocomplete. `metricName` limits choices
        to one metric."""
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        params = _MetricAttributeValuesParamsSerializer(data=request.query_params)
        params.is_valid(raise_exception=True)

        try:
            results = list_metric_attribute_values(
                team=self.team,
                key=params.validated_data["key"],
                metric_name=params.validated_data["metricName"],
                search=params.validated_data["value"],
                date_from=params.validated_data["dateFrom"],
                date_to=params.validated_data["dateTo"],
                limit=params.validated_data["limit"],
            )
        except ValueError as exc:
            raise ParseError(str(exc))

        return Response({"results": results}, status=status.HTTP_200_OK)

    @extend_schema(
        request=_MetricVariableOptionsRequestSerializer,
        responses={200: _MetricVariableOptionsResponseSerializer},
    )
    @action(
        detail=False,
        methods=["POST"],
        required_scopes=["metrics:read"],
        throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
    )
    def variable_options(self, request: Request, *args, **kwargs) -> Response:
        """The options of one dashboard variable, for the variable selects on dashboards."""
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        body = _MetricVariableOptionsRequestSerializer(data=request.data)
        body.is_valid(raise_exception=True)
        data = body.validated_data
        # PromQL goes to Snuffle, which has its own gate, as the PromQL insights and the Prometheus API do.
        if data["source"] == MetricVariableSource.PROMQL and not posthog_feature_flag_enabled(
            SNUFFLE_API_FEATURE_FLAG,
            str(cast(User, request.user).distinct_id),
            organization_id=self.team.organization_id,
            team_id=self.team.pk,
        ):
            raise PermissionDenied("PromQL variable queries are not enabled for this project.")
        self._enforce_api_queries_budget()
        variables = [
            MetricsDashboardVariable(
                name=selection["name"],
                source=MetricsDashboardVariableSource.CUSTOM,
                includeAll=selection["all"],
                allValue=selection["allValue"],
                current=MetricsDashboardVariableSelection(values=selection["values"], all=selection["all"]),
            )
            for selection in data["variables"]
        ]
        try:
            results = list_metric_variable_options(
                team=self.team,
                source=MetricsDashboardVariableSource(data["source"]),
                query=data["query"],
                custom_values=data["customValues"],
                regex=data["regex"],
                variables=variables,
                date_from=data["dateFrom"],
                date_to=data["dateTo"],
            )
        except ConcurrencyLimitExceeded as exc:
            raise Throttled(wait=CONCURRENCY_LIMIT_RETRY_AFTER_SECONDS, detail=CONCURRENCY_LIMIT_USER_MESSAGE) from exc
        except ValueError as exc:
            raise ParseError(str(exc))

        return Response({"results": results}, status=status.HTTP_200_OK)

    def _enforce_api_queries_budget(self) -> None:
        if get_query_tag_value("access_method") != "personal_api_key":
            return
        tag_queries(api_queries_budgeted=True)
        if api_queries_budget_enforcement_enabled(self.team):
            budget = get_api_queries_budget_status(self.team)
            if budget is not None and budget.remaining_bytes <= 0:
                raise Throttled(
                    wait=budget.retry_after_seconds,
                    detail="ClickHouse query byte budget exhausted. Try again later.",
                )

    @extend_schema(request=_MetricQueryRequestSerializer, responses={200: _MetricQueryResponseSerializer})
    @action(
        detail=False,
        methods=["POST"],
        required_scopes=["metrics:read"],
        throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
    )
    def query(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        body = _MetricQueryRequestSerializer(data=request.data)
        body.is_valid(raise_exception=True)
        query_data = body.validated_data["query"]

        date_to: dt.datetime = query_data.get("dateTo") or timezone.now()
        if (query_data.get("promql") or "").strip():
            return self._run_promql_query(request, query_data, date_to)
        try:
            if query_data.get("clauses"):
                clauses = tuple(_build_clause(c, name=c["name"]) for c in query_data["clauses"])
            else:
                clauses = (_build_clause(query_data, name="a"),)
            metric_request = MetricQueryRequest(
                clauses=clauses,
                date_from=query_data["dateFrom"],
                date_to=date_to,
                interval=query_data.get("interval"),
                formula=query_data.get("formula"),
            )
            series = run_metric_query(team=self.team, request=metric_request)
        except ValueError as exc:
            raise ParseError(str(exc))

        report_user_action(
            request.user,
            "metrics query ran",
            {
                "language": "builder",
                "aggregations": sorted({c.aggregation.value for c in clauses}),
                "clause_count": len(clauses),
                "has_formula": metric_request.formula is not None,
                "series_count": len(series),
                "result_count": sum(len(s.points) for s in series),
            },
            team=self.team,
            request=request,
        )

        return _series_response(series)

    def _run_promql_query(self, request: Request, query_data: dict, date_to: dt.datetime) -> Response:
        if not posthog_feature_flag_enabled(
            SNUFFLE_API_FEATURE_FLAG,
            str(cast(User, request.user).distinct_id),
            organization_id=self.team.organization_id,
            team_id=self.team.pk,
        ):
            raise PermissionDenied("PromQL queries are not enabled for this project.")
        self._enforce_api_queries_budget()
        try:
            series = run_promql_query(
                team=self.team,
                expr=query_data["promql"],
                date_from=query_data["dateFrom"],
                date_to=date_to,
                interval=query_data.get("interval"),
            )
        except ConcurrencyLimitExceeded as exc:
            raise Throttled(wait=CONCURRENCY_LIMIT_RETRY_AFTER_SECONDS, detail=CONCURRENCY_LIMIT_USER_MESSAGE) from exc
        except PromQLQueryError as exc:
            if exc.transient:
                raise _PromQLBackendUnavailable(str(exc)) from exc
            raise ParseError(str(exc))
        except ValueError as exc:
            raise ParseError(str(exc))

        report_user_action(
            request.user,
            "metrics query ran",
            {
                "language": "promql",
                "series_count": len(series),
                "result_count": sum(len(s.points) for s in series),
            },
            team=self.team,
            request=request,
        )
        return _series_response(series)

    @extend_schema(request=_MetricSamplesRequestSerializer, responses={200: _MetricSamplesResponseSerializer})
    @action(detail=False, methods=["POST"], required_scopes=["metrics:read"])
    def samples(self, request: Request, *args, **kwargs) -> Response:
        """Raw individual emissions for a metric (the events model), newest
        first — backs the Samples view and the metric->trace pivot."""
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        body = _MetricSamplesRequestSerializer(data=request.data)
        body.is_valid(raise_exception=True)
        query_data = body.validated_data["query"]

        filters = tuple(
            MetricFilter(key=f["key"], op=FilterOp(f["op"]), value=f["value"], scope=AttributeScope(f["scope"]))
            for f in query_data.get("filters") or []
        )
        try:
            samples = list_metric_event_samples(
                team=self.team,
                metric_name=query_data.get("metricName") or None,
                date_from=query_data["dateFrom"],
                date_to=query_data.get("dateTo") or timezone.now(),
                trace_id=query_data.get("traceId") or None,
                span_id=query_data.get("spanId") or None,
                filters=filters,
                metric_type=MetricType(query_data["metricType"]) if query_data.get("metricType") else None,
                limit=query_data.get("limit") or 100,
            )
        except ValueError as exc:
            raise ParseError(str(exc))

        report_user_action(
            request.user,
            "metrics samples listed",
            {
                "sample_count": len(samples),
                "has_trace_filter": bool(query_data.get("traceId")),
                "filter_count": len(filters),
            },
            team=self.team,
            request=request,
        )

        return Response({"results": [asdict(s) for s in samples]}, status=status.HTTP_200_OK)

    @extend_schema(
        parameters=[_MetricErrorSpikesParamsSerializer], responses={200: _MetricErrorSpikesResponseSerializer}
    )
    # Both scopes: the response is Error Tracking data, so a token scoped to metrics
    # alone must not reach it (scopes gate the token; the access-control check below
    # gates the user).
    @action(detail=False, methods=["GET"], required_scopes=["metrics:read", "error_tracking:read"])
    def error_spikes(self, request: Request, *args, **kwargs) -> Response:
        """Error Tracking issue spikes detected in a time window — backs the
        metrics chart's error-spike overlay (PoC). Team-wide: not yet scoped
        to the metric's own service."""
        # Layered on top of the viewset's `metrics` gate: the overlay is a PoC
        # kept to staff only, so it needs its own flag even once metrics is on.
        if not posthog_feature_flag_enabled(
            METRICS_ERROR_OVERLAYS_FEATURE_FLAG,
            str(cast(User, request.user).distinct_id),
            organization_id=self.team.organization_id,
            team_id=self.team.pk,
        ):
            raise PermissionDenied("The metrics error-spike overlay is not enabled for this user.")

        # This action serves Error Tracking data (issue ids and names), so the caller
        # needs view access to that resource too — metrics access alone must not leak
        # it. The frontend hides the overlay on the same condition.
        if not self.user_access_control.check_access_level_for_resource("error_tracking", "viewer"):
            raise PermissionDenied("You do not have access to error tracking.")

        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        params = _MetricErrorSpikesParamsSerializer(data=request.query_params)
        params.is_valid(raise_exception=True)

        spikes = list_metric_error_spikes(
            team=self.team,
            date_from=params.validated_data["dateFrom"],
            date_to=params.validated_data.get("dateTo") or timezone.now(),
        )

        return Response({"results": [asdict(s) for s in spikes]}, status=status.HTTP_200_OK)

    @extend_schema(request=_MetricAnomalyRequestSerializer, responses={200: _MetricAnomalyReportSerializer})
    @action(
        detail=False,
        methods=["POST"],
        required_scopes=["metrics:read"],
        throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
    )
    def characterize(self, request: Request, *args, **kwargs) -> Response:
        """Characterize a metric anomaly: compare an anomaly window against a
        baseline, find the onset, and rank which label values moved."""
        tag_queries(product=Product.METRICS, feature=Feature.QUERY)

        body = _MetricAnomalyRequestSerializer(data=request.data)
        body.is_valid(raise_exception=True)
        query_data = body.validated_data["query"]

        filters = tuple(
            MetricFilter(key=f["key"], op=FilterOp(f["op"]), value=f["value"], scope=AttributeScope(f["scope"]))
            for f in query_data.get("filters") or []
        )
        try:
            report = characterize_metric_anomaly(
                team=self.team,
                metric_name=query_data["metricName"],
                anomaly_from=query_data["anomalyFrom"],
                anomaly_to=query_data.get("anomalyTo") or timezone.now(),
                baseline_from=query_data.get("baselineFrom"),
                baseline_to=query_data.get("baselineTo"),
                aggregation=query_data.get("aggregation"),
                quantile=query_data.get("quantile"),
                filters=filters,
                candidate_keys=tuple(query_data["candidateKeys"]) if query_data.get("candidateKeys") else None,
            )
        except ValueError as exc:
            raise ParseError(str(exc))

        report_user_action(
            request.user,
            "metrics anomaly characterized",
            {
                "aggregation": report.aggregation,
                "direction": report.direction,
                "mover_count": len(report.top_movers),
            },
            team=self.team,
            request=request,
        )

        return Response(asdict(report), status=status.HTTP_200_OK)