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.

103 KB
Raw Blame
import re
import json
import base64
import datetime as dt
from time import monotonic
from typing import Any

from django.db import models
from django.http import HttpRequest, HttpResponseBase
from django.utils import timezone

import structlog
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import PolymorphicProxySerializer, extend_schema, extend_schema_field
from opentelemetry import trace
from pydantic import ValidationError
from redis.exceptions import RedisError
from rest_framework import serializers, status, viewsets
from rest_framework.decorators import action
from rest_framework.exceptions import ParseError, Throttled
from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework.throttling import BaseThrottle

from posthog.schema import DateRange, LogAttributesQuery, LogsOrderBy, LogsQuery, LogValuesQuery, PropertyGroupFilter

from posthog.hogql.errors import QueryError

from posthog.api.documentation import PropertyGroupOperator, _FallbackSerializer
from posthog.api.mixins import PydanticModelMixin
from posthog.api.property_value_metrics import PROPERTY_VALUES_DURATION
from posthog.api.query import CONCURRENCY_LIMIT_USER_MESSAGE
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.auth import PersonalAPIKeyAuthentication
from posthog.clickhouse.client.limit import ConcurrencyLimitExceeded, ConcurrencySlot, get_logs_api_team_rate_limiter
from posthog.clickhouse.query_tagging import Feature, Product, tag_queries
from posthog.errors import ExposedCHQueryError
from posthog.event_usage import get_request_analytics_properties, report_user_action
from posthog.hogql_queries.query_runner import ExecutionMode
from posthog.hogql_queries.utils.time_sliced_query import time_sliced_results
from posthog.models import User
from posthog.models.property.property import STRING_PREFIX_SUFFIX_OPERATORS
from posthog.rate_limit import ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle
from posthog.tasks.exporter import export_asset

from products.exports.backend.models.exported_asset import ExportedAsset
from products.logs.backend.column_expressions import canonical_key
from products.logs.backend.count_query_runner import CountQueryRunner
from products.logs.backend.count_ranges_query_runner import (
    DEFAULT_TARGET_BUCKETS,
    MAX_TARGET_BUCKETS,
    CountRangesQueryRunner,
)
from products.logs.backend.group_by_query_runner import (
    DEFAULT_GROUP_LIMIT,
    GROUP_SOURCES,
    MAX_GROUP_DIMENSIONS,
    MAX_GROUP_LIMIT,
    ORDER_FIELDS,
    LogsGroupByQueryRunner,
)
from products.logs.backend.has_logs_query_runner import team_has_logs
from products.logs.backend.impact_query_runner import ImpactQueryRunner
from products.logs.backend.log_attributes_query_runner import LogAttributesQueryRunner
from products.logs.backend.log_facet_values_query_runner import FACET_FIELDS, LogFacetValuesQueryRunner
from products.logs.backend.log_values_query_runner import LogValuesQueryRunner
from products.logs.backend.logs_query_runner import (
    MAX_CUSTOM_COLUMNS,
    CachedLogsQueryResponse,
    LogsQueryResponse,
    LogsQueryRunner,
)
from products.logs.backend.pattern_diff import run_patterns_diff
from products.logs.backend.patterns_query_runner import PatternsQueryRunner
from products.logs.backend.presentation.views.alerts_api import LogsAlertViewSet
from products.logs.backend.presentation.views.explain import LogExplainViewSet
from products.logs.backend.presentation.views.metric_rules_api import LogsMetricRuleViewSet
from products.logs.backend.presentation.views.patterns_diff_fields import (
    PatternDiffEntryFields,
    PatternsDiffBodyFields,
    PatternsDiffResponseFields,
)
from products.logs.backend.presentation.views.retention_api import LogsRetentionRuleViewSet
from products.logs.backend.presentation.views.sampling_api import LogsSamplingRuleViewSet
from products.logs.backend.presentation.views.views_api import LogsViewViewSet
from products.logs.backend.services_query_runner import (
    COMPARE_MODES,
    LogsCompareMode,
    LogsServicesSource,
    LogsServiceStatus,
    ServicesQueryRunner,
)
from products.logs.backend.sparkline_query_runner import SparklineQueryRunner

__all__ = [
    "LogsViewSet",
    "LogExplainViewSet",
    "LogsAlertViewSet",
    "LogsMetricRuleViewSet",
    "LogsRetentionRuleViewSet",
    "LogsSamplingRuleViewSet",
    "LogsViewViewSet",
]

tracer = trace.get_tracer(__name__)
logger = structlog.get_logger(__name__)
LOGS_MAX_EXPORT_ROWS = 10_000
LOGS_API_SLOT_TTL_MARGIN_SECONDS = 30
MAX_ATTRIBUTE_KEYS = 100


class DateRangeSerializer(serializers.Serializer):
    date_from = serializers.CharField(help_text='Start of date range (ISO 8601 format, e.g., "2024-01-01T00:00:00Z").')
    date_to = serializers.CharField(help_text='End of date range (ISO 8601 format, e.g., "2024-01-02T00:00:00Z").')


class SparklineQuerySerializer(serializers.Serializer):
    dateRange = DateRangeSerializer(help_text="Date range for the sparkline query.")
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=list,
        help_text="Filter by severity levels (trace, debug, info, warn, error, fatal).",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=list,
        help_text="Filter by service names.",
    )
    searchTerm = serializers.CharField(
        required=False,
        allow_null=True,
        default=None,
        help_text="Free text search term to filter log entries.",
    )
    filterGroup = serializers.JSONField(
        required=False,
        allow_null=True,
        default=None,
        help_text="Property filter group object for structured filtering.",
    )
    sparklineBreakdownBy = serializers.ChoiceField(
        choices=["severity", "service"],
        required=False,
        allow_null=True,
        default=None,
        help_text="Break down sparkline data by severity level or service name (default: severity).",
    )


class SparklineRequestSerializer(serializers.Serializer):
    query = SparklineQuerySerializer(help_text="Sparkline query parameters.")


# Serializers below are used exclusively for OpenAPI spec generation via
# drf-spectacular. They are NOT used for request validation — the existing
# manual parsing in LogsViewSet is unchanged.

_LOG_PROPERTY_TYPE_CHOICES = ["log", "log_attribute", "log_resource_attribute"]
_LOG_STRING_OPERATORS = [
    "exact",
    "is_not",
    "icontains",
    "not_icontains",
    *STRING_PREFIX_SUFFIX_OPERATORS,
    "regex",
    "not_regex",
]
_LOG_NUMERIC_OPERATORS = ["exact", "gt", "lt"]
_LOG_ARRAY_OPERATORS = ["exact", "is_not"]
_LOG_DATE_OPERATORS = ["is_date_exact", "is_date_before", "is_date_after"]
_LOG_EXISTENCE_OPERATORS = ["is_set", "is_not_set"]
_LOG_ALL_OPERATORS = (
    _LOG_STRING_OPERATORS
    + _LOG_NUMERIC_OPERATORS
    + _LOG_ARRAY_OPERATORS
    + _LOG_DATE_OPERATORS
    + _LOG_EXISTENCE_OPERATORS
)


class _DateRangeSerializer(serializers.Serializer):
    date_from = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Start of the date range. Accepts ISO 8601 timestamps or relative formats: -7d, -1h, -1mStart, etc.",
    )
    date_to = serializers.CharField(
        required=False,
        allow_null=True,
        help_text='End of the date range. Same format as date_from. Omit or null for "now".',
    )


class _LogPropertyFilterSerializer(serializers.Serializer):
    key = serializers.CharField(
        help_text=(
            'Attribute key. For type "log", use "message" for the body text, or a log column: '
            '"pattern" and "pattern_version" (the patterns pivot), "severity_level", "service_name", '
            '"trace_id", "span_id". For "log_attribute"/"log_resource_attribute", use the attribute '
            'key (e.g. "k8s.container.name").'
        ),
    )
    type = serializers.ChoiceField(
        choices=_LOG_PROPERTY_TYPE_CHOICES,
        help_text='"log" filters the log body/message. "log_attribute" filters log-level attributes. "log_resource_attribute" filters resource-level attributes.',
    )
    operator = serializers.ChoiceField(
        choices=_LOG_ALL_OPERATORS,
        help_text="Comparison operator.",
    )
    value = serializers.JSONField(
        required=False,
        allow_null=True,
        help_text="Value to compare against. String, number, or array of strings. Omit for is_set/is_not_set operators.",
    )


class _LogsFilterInnerGroupSerializer(serializers.Serializer):
    type = serializers.ChoiceField(
        choices=PropertyGroupOperator.choices, help_text="How to combine the filters in `values`."
    )
    values = _LogPropertyFilterSerializer(many=True, help_text="Property filters in this group.")


class _LogsFilterGroupSerializer(serializers.Serializer):
    type = serializers.ChoiceField(
        choices=PropertyGroupOperator.choices, help_text="How to combine the groups in `values`."
    )
    values = _LogsFilterInnerGroupSerializer(many=True, help_text="Groups of property filters.")


# `_normalize_filter_group` accepts both forms and reads a flat list as one AND group.
@extend_schema_field(
    PolymorphicProxySerializer(
        component_name="LogsFilterGroupInput",
        serializers=[_LogPropertyFilterSerializer(many=True), _LogsFilterGroupSerializer],
        resource_type_field_name=None,
        many=False,
    )
)
class _LogsFilterGroupField(serializers.JSONField):
    pass


class _LogsAttributesQuerySerializer(serializers.Serializer):
    search = serializers.CharField(required=False, help_text="Search filter for attribute names")
    search_values = serializers.BooleanField(
        required=False,
        default=False,
        help_text="When true, the search query also matches attribute values (not just keys). Each result indicates whether it matched on key or value.",
    )
    attribute_type = serializers.ChoiceField(
        choices=["log", "resource"],
        required=False,
        help_text='Type of attributes: "log" for log attributes, "resource" for resource attributes. Defaults to "log".',
    )
    limit = serializers.IntegerField(required=False, min_value=1, max_value=100, help_text="Max results (default: 100)")
    offset = serializers.IntegerField(required=False, min_value=0, help_text="Pagination offset (default: 0)")
    dateRange = _DateRangeSerializer(
        required=False,
        help_text="Date range to search within. Defaults to last hour.",
    )
    keys = serializers.CharField(
        required=False,
        help_text="Comma-separated list of attribute keys. The endpoint returns only keys that exactly match an entry in the list.",
    )
    date_from = serializers.CharField(
        required=False,
        help_text="Start of the range as a top-level parameter. The endpoint ignores it when you send dateRange.",
    )
    date_to = serializers.CharField(
        required=False,
        help_text="End of the range as a top-level parameter. The endpoint ignores it when you send dateRange.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=[],
        help_text="Filter attributes to those appearing in logs from these services.",
    )
    filterGroup = serializers.ListField(
        child=_LogPropertyFilterSerializer(),
        required=False,
        default=[],
        help_text="Property filters to narrow which logs are scanned for attributes.",
    )


class _LogsValuesQuerySerializer(serializers.Serializer):
    key = serializers.CharField(help_text="The attribute key to get values for")
    attribute_type = serializers.ChoiceField(
        choices=["log", "resource"],
        required=False,
        help_text='Type of attribute: "log" or "resource". Defaults to "log".',
    )
    value = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text="Search filter for attribute values. Omit it or pass an empty string to list all values.",
    )
    dateRange = _DateRangeSerializer(
        required=False,
        help_text="Date range to search within. Defaults to last hour.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=[],
        help_text="Filter values to those appearing in logs from these services.",
    )
    filterGroup = serializers.ListField(
        child=_LogPropertyFilterSerializer(),
        required=False,
        default=[],
        help_text="Property filters to narrow which logs are scanned for values.",
    )


class OrderBy(models.TextChoices):
    LATEST = "latest", "latest"
    EARLIEST = "earliest", "earliest"


# Scope fields ride on every logs body that reaches the query runner, so they are built here
# rather than redeclared per serializer — the help text is what drf-spectacular ships into the
# generated TypeScript and the MCP tool schemas, and six copies drift.
def _person_scope_field(noun: str) -> serializers.CharField:
    return serializers.CharField(
        required=False,
        help_text=(
            f"Scope {noun} to one person (UUID or numeric ID). Expanded server-side to the person's "
            "distinct IDs and matched against the team's configured distinct-id log attribute keys."
        ),
    )


def _session_scope_field(noun: str) -> serializers.CharField:
    return serializers.CharField(
        required=False,
        help_text=(
            f"Scope {noun} to one session ID. Matched server-side against the team's configured "
            "session-id log attribute keys plus the built-in conventions, in both log attributes "
            "and resource attributes."
        ),
    )


# The query action uses _LOGS_QUERY_SERVER_DEFAULT_LIMIT when the body omits limit, and caps larger values.
_LOGS_QUERY_MAX_LIMIT = 2000
_LOGS_QUERY_SERVER_DEFAULT_LIMIT = 1000


class _LogsQueryBodySerializer(serializers.Serializer):
    dateRange = _DateRangeSerializer(
        required=False,
        help_text="Date range for the query. Defaults to last hour.",
    )
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=[],
        help_text="Filter by log severity levels.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=[],
        help_text="Filter by service names.",
    )
    orderBy = serializers.ChoiceField(
        choices=OrderBy.choices,
        required=False,
        help_text="Order results by timestamp.",
    )
    searchTerm = serializers.CharField(required=False, help_text="Full-text search term to filter log bodies.")
    filterGroup = _LogsFilterGroupField(
        required=False,
        help_text=(
            "Property filters for the query. Pass a list of filters, which are all combined with AND, "
            "or a filter group object with nested AND/OR groups."
        ),
    )
    limit = serializers.IntegerField(
        required=False,
        default=100,
        min_value=1,
        help_text=f"Max results. Values above {_LOGS_QUERY_MAX_LIMIT} are capped at {_LOGS_QUERY_MAX_LIMIT}.",
    )
    after = serializers.CharField(required=False, help_text="Pagination cursor from previous response.")
    excludeAttributes = serializers.BooleanField(
        required=False,
        default=False,
        help_text="Omit the per-log attributes and resource_attributes maps from results to keep payloads compact. Defaults to false.",
    )
    customColumns = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=[],
        help_text=(
            "Custom column expressions evaluated per log row. Each entry is either a source-prefixed shorthand "
            "(`attributes.<key>`, `resource_attributes.<key>`, `body.<json.path>`) or a scalar HogQL expression "
            "(`upper(level)`, `coalesce(attributes['a'], attributes['b'])`). Aggregations and subqueries are rejected. "
            "Values come back on each result row keyed by the aliases echoed in the response `columns` field."
        ),
    )
    personId = _person_scope_field("results")
    sessionId = _session_scope_field("results")


class _LogsBodyLimitSerializer(serializers.Serializer):
    # Validates only the limit key of a raw query body; the other keys pass through untouched.
    limit = serializers.IntegerField(required=False, allow_null=True, min_value=1, help_text="Max results.")


class _LogsQueryRequestSerializer(serializers.Serializer):
    query = _LogsQueryBodySerializer(help_text="The logs query to execute.")


class _LogsSparklineBodySerializer(serializers.Serializer):
    dateRange = _DateRangeSerializer(
        required=False,
        help_text="Date range for the sparkline. Defaults to last hour.",
    )
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=[],
        help_text="Filter by log severity levels.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=[],
        help_text="Filter by service names.",
    )
    searchTerm = serializers.CharField(required=False, help_text="Full-text search term to filter log bodies.")
    filterGroup = _LogsFilterGroupField(
        required=False,
        help_text=(
            "Property filters for the query. Pass a list of filters, which are all combined with AND, "
            "or a filter group object with nested AND/OR groups."
        ),
    )
    sparklineBreakdownBy = serializers.ChoiceField(
        choices=["severity", "service"],
        required=False,
        help_text='Break down sparkline by "severity" (default) or "service".',
    )
    sparklineRankBy = serializers.ChoiceField(
        choices=["count", "bytes"],
        required=False,
        help_text='Rank breakdown values by "count" (default) or "bytes" before collapsing the tail into "other".',
    )
    personId = _person_scope_field("results")
    sessionId = _session_scope_field("results")


class _LogsSparklineRequestSerializer(serializers.Serializer):
    query = _LogsSparklineBodySerializer(help_text="The sparkline query to execute.")


class _LogsCountBodySerializer(serializers.Serializer):
    dateRange = _DateRangeSerializer(
        required=False,
        help_text="Date range for the count. Defaults to last hour.",
    )
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=list,
        help_text="Filter by log severity levels.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=list,
        help_text="Filter by service names.",
    )
    searchTerm = serializers.CharField(required=False, help_text="Full-text search term to filter log bodies.")
    filterGroup = serializers.ListField(
        child=_LogPropertyFilterSerializer(),
        required=False,
        default=list,
        help_text="Property filters for the query.",
    )


class _LogsCountRequestSerializer(serializers.Serializer):
    query = _LogsCountBodySerializer(help_text="The count query to execute.")


class _LogsImpactRequestSerializer(serializers.Serializer):
    query = _LogsCountBodySerializer(
        help_text="The impact query to execute. Takes the same filters as the count query."
    )


class _LogsImpactTopValueSerializer(serializers.Serializer):
    value = serializers.CharField(help_text="The session ID or person distinct ID.")
    count = serializers.IntegerField(
        help_text="Approximate number of matching logs that carry this value (topK estimate)."
    )


class _LogsImpactGroupKeySerializer(serializers.Serializer):
    source = serializers.ChoiceField(  # type: ignore[assignment]  # field named `source` shadows DRF Field.source
        choices=list(GROUP_SOURCES),
        help_text='Attribute map the key lives in, in the group-by endpoint\'s vocabulary: "log" or "resource".',
    )
    key = serializers.CharField(help_text="The attribute key that carries the ID on most matching logs.")


class _LogsImpactResponseSerializer(serializers.Serializer):
    total = serializers.IntegerField(help_text="Number of log entries matching the filters.")
    logsWithSessionId = serializers.IntegerField(
        help_text="How many of the matching logs carry a session ID under the team's configured or conventional attribute keys."
    )
    sessions = serializers.IntegerField(
        help_text="Estimated number of unique session IDs across the matching logs (HyperLogLog, about 1-2% error)."
    )
    logsWithDistinctId = serializers.IntegerField(
        help_text="How many of the matching logs carry a person distinct ID under the team's configured or conventional attribute keys."
    )
    users = serializers.IntegerField(
        help_text="Estimated number of unique distinct IDs across the matching logs (HyperLogLog, about 1-2% error)."
    )
    topSessions = _LogsImpactTopValueSerializer(
        many=True,
        help_text="Top session IDs on the matching logs, ordered by log count descending (topK, at most 5).",
    )
    topUsers = _LogsImpactTopValueSerializer(
        many=True,
        help_text="Top person distinct IDs on the matching logs, ordered by log count descending (topK, at most 5).",
    )
    sessionGroupKey = _LogsImpactGroupKeySerializer(
        allow_null=True,
        help_text=(
            "The dimension that carries the session ID on most matching logs. Group by this dimension to "
            "drill into the sessions behind the counts. Null when no matching log carries a session ID."
        ),
    )
    personGroupKey = _LogsImpactGroupKeySerializer(
        allow_null=True,
        help_text=(
            "The dimension that carries the person distinct ID on most matching logs. Group by this dimension to "
            "drill into the users behind the counts. Null when no matching log carries a distinct ID."
        ),
    )


class _LogFacetValueSerializer(serializers.Serializer):
    value = serializers.CharField(help_text="The facet value (e.g. a severity level or service name).")
    count = serializers.IntegerField(
        help_text="Number of matching log records, with all active filters applied except this facet's own selection."
    )


class _LogsFacetValuesResponseSerializer(serializers.Serializer):
    results = _LogFacetValueSerializer(
        many=True, help_text="Facet values with cross-filtered counts, ordered by count descending."
    )


class _LogsFacetValuesBodySerializer(serializers.Serializer):
    facetField = serializers.ChoiceField(
        choices=["severity_text", "service_name"],
        required=False,
        allow_null=True,
        help_text="Top-level column to facet on. Provide exactly one of facetField, facetResourceAttribute or "
        "facetAttribute. Counts come from a rollup with 5-minute buckets, so the window widens to the buckets "
        "that contain date_from and date_to. The rollup honours severityLevels and serviceNames, but not body "
        "search, log-attribute filters, or resource-attribute filters. When personId or sessionId is set, counts "
        "come from the logs table with the exact window and every other filter. Both paths exclude this facet's "
        "own filter.",
    )
    facetResourceAttribute = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Resource attribute key to facet on (e.g. 'k8s.namespace.name'). Provide exactly one of "
        "facetField, facetResourceAttribute or facetAttribute. Its own log_resource_attribute filter is excluded "
        "so counts reflect the other active filters.",
    )
    facetAttribute = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Log attribute key to facet on (e.g. 'log.iostream'). Provide exactly one of facetField, "
        "facetResourceAttribute or facetAttribute. Counts honour severity, service and resource-attribute "
        "filters, but not body search, other log-attribute filters, or this facet's own filter.",
    )
    dateRange = _DateRangeSerializer(required=False, help_text="Date range. Defaults to last hour.")
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=list,
        help_text="Filter by log severity levels (ignored when faceting on severity_text).",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=list,
        help_text="Filter by service names (ignored when faceting on service_name).",
    )
    searchTerm = serializers.CharField(required=False, help_text="Full-text search term to filter log bodies.")
    facetSearch = serializers.CharField(
        required=False,
        help_text="Type-ahead filter over the faceted field's own values (case-insensitive substring match). "
        "Distinct from searchTerm, which searches log bodies.",
    )
    filterGroup = serializers.ListField(
        child=_LogPropertyFilterSerializer(),
        required=False,
        default=list,
        help_text="Property filters for the query.",
    )
    personId = _person_scope_field("counts")
    sessionId = _session_scope_field("counts")


class _LogsFacetValuesRequestSerializer(serializers.Serializer):
    query = _LogsFacetValuesBodySerializer(help_text="The facet values query to execute.")


class _LogsCountRangesBodySerializer(serializers.Serializer):
    dateRange = _DateRangeSerializer(
        required=False,
        help_text=(
            "Window to bucket. Defaults to last hour. Use a bucket's date_from/date_to "
            "from a prior response to recursively narrow into a sub-range."
        ),
    )
    targetBuckets = serializers.IntegerField(
        required=False,
        min_value=1,
        max_value=MAX_TARGET_BUCKETS,
        default=DEFAULT_TARGET_BUCKETS,
        help_text=(
            "Approximate number of buckets to return. The bucket interval is picked "
            "adaptively from a fixed list (1/5/10s, 1/2/5/10/15/30/60/120/240/360/720/1440m) "
            f"to land near this target. Defaults to {DEFAULT_TARGET_BUCKETS}, capped at {MAX_TARGET_BUCKETS}."
        ),
    )
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=list,
        help_text="Filter by log severity levels. Applied before bucketing.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=list,
        help_text="Filter by service names. Applied before bucketing.",
    )
    searchTerm = serializers.CharField(
        required=False,
        help_text="Full-text search across log bodies. Applied before bucketing.",
    )
    filterGroup = serializers.ListField(
        child=_LogPropertyFilterSerializer(),
        required=False,
        default=list,
        help_text="Property filters applied before bucketing. Same shape as `query-logs`.",
    )


class _LogsCountRangesRequestSerializer(serializers.Serializer):
    query = _LogsCountRangesBodySerializer(help_text="The bucketed-count query to execute.")


class _LogsCountRangeBucketSerializer(serializers.Serializer):
    date_from = serializers.CharField(
        help_text="Bucket start as ISO 8601 timestamp. Inclusive lower bound. Pass back as `dateRange.date_from` to drill in.",
    )
    date_to = serializers.CharField(
        help_text="Bucket end as ISO 8601 timestamp. Exclusive upper bound. Pass back as `dateRange.date_to` to drill in.",
    )
    count = serializers.IntegerField(help_text="Log entries matching the filters within this bucket.")


class _LogsCountRangesResponseSerializer(serializers.Serializer):
    ranges = _LogsCountRangeBucketSerializer(
        many=True,
        help_text=(
            "Buckets ordered by `date_from` ascending. Empty buckets are omitted — infer "
            "gaps by comparing each bucket's `date_to` to the next bucket's `date_from`."
        ),
    )
    interval = serializers.CharField(
        help_text=(
            'Short-form duration of the chosen bucket width (e.g. "1h", "5m", "30s", "1d"). '
            "Informational only — use each bucket's `date_from`/`date_to` for follow-up queries."
        ),
    )


class _LogsServicesBodySerializer(serializers.Serializer):
    dateRange = _DateRangeSerializer(
        required=False,
        help_text="Date range for the services aggregation. Defaults to last hour.",
    )
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=list,
        help_text="Filter by log severity levels.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=list,
        help_text="Restrict the aggregation to these service names.",
    )
    searchTerm = serializers.CharField(required=False, help_text="Full-text search term to filter log bodies.")
    serviceNameSearch = serializers.CharField(
        required=False,
        max_length=200,
        help_text=(
            "Case-insensitive substring match on service name, applied before aggregation. "
            "Use to reach services beyond the response cap."
        ),
    )
    filterGroup = serializers.ListField(
        child=_LogPropertyFilterSerializer(),
        required=False,
        default=list,
        help_text="Property filters for the query.",
    )
    environment = serializers.CharField(
        required=False,
        max_length=200,
        help_text=(
            "Deployment environment, matched without case against the first set resource attribute of "
            'deployment.environment.name, deployment.environment and env. "(none)" matches logs without one.'
        ),
    )
    compare = serializers.ChoiceField(
        choices=LogsCompareMode.choices,
        default="none",
        help_text=(
            "Baseline window for per-service status: the window just before, the same window a day or a week "
            "earlier, or none. Silent services (logs in the baseline, none now) only appear with a baseline."
        ),
    )


class _LogsServicesRequestSerializer(serializers.Serializer):
    query = _LogsServicesBodySerializer(help_text="The services aggregation query to execute.")
    baselineDateRange = _DateRangeSerializer(
        required=False, help_text="Explicit baseline window. Takes precedence over `query.compare`."
    )


class _LogEntrySerializer(serializers.Serializer):
    uuid = serializers.CharField()
    timestamp = serializers.CharField(help_text="ISO 8601 timestamp of the original log event.")
    observed_timestamp = serializers.CharField(
        help_text="ISO 8601 timestamp the log pipeline observed the event (may differ from `timestamp`).",
    )
    body = serializers.CharField()
    severity_text = serializers.CharField(
        help_text='Log severity as a string (e.g. "info", "error"). Preferred over severity_number.',
    )
    severity_number = serializers.IntegerField(
        help_text="Log severity as a numeric code. Redundant with severity_text; kept for OpenTelemetry compatibility.",
    )
    level = serializers.CharField(help_text="ClickHouse alias for severity_text. Redundant; prefer severity_text.")
    trace_id = serializers.CharField(
        help_text='Trace ID. Returns "00000000000000000000000000000000" when not set (padding, not null).',
    )
    span_id = serializers.CharField(
        help_text='Span ID. Returns "0000000000000000" when not set (padding, not null).',
    )
    attributes = serializers.DictField(
        child=serializers.CharField(allow_blank=True),
        help_text="Log-level attributes as a string-keyed map. Values are strings (numeric/datetime attributes are also accessible via materialized columns).",
    )
    resource_attributes = serializers.DictField(
        child=serializers.CharField(allow_blank=True),
        help_text="Resource-level attributes (service.name, k8s.*, host.hostname, etc.) as a string-keyed map. Repeats across all logs from the same pod/host.",
    )
    event_name = serializers.CharField(required=False, allow_blank=True, help_text="OpenTelemetry event name, if set.")
    instrumentation_scope = serializers.CharField(
        allow_blank=True, help_text="OpenTelemetry instrumentation scope name. Empty when not set."
    )
    resource_fingerprint = serializers.CharField(
        help_text="Hash of the resource attributes. Logs from the same pod or host share it."
    )
    live_logs_checkpoint = serializers.DateTimeField(
        allow_null=True,
        help_text=(
            "Latest timestamp up to which ingestion is known to be complete. The same on every row. "
            "Logs newer than it can still arrive."
        ),
    )


class _LogsQueryResponseSerializer(serializers.Serializer):
    query = serializers.DictField(
        help_text="The parsed query that was executed, echoed back for confirmation.",
    )
    results = _LogEntrySerializer(many=True, help_text="Log entries matching the query.")
    hasMore = serializers.BooleanField(help_text="True if more results exist beyond this page.")
    nextCursor = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Opaque cursor to pass as `after` in the next request to fetch the next page. Null when hasMore is false.",
    )
    maxExportableLogs = serializers.IntegerField(
        help_text="Maximum number of rows the `export` endpoint will produce — informational.",
    )
    columns = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        allow_null=True,
        help_text=(
            "Aliases for the requested `customColumns`, in request order. Each result row carries its "
            "custom column values under these keys. Null when no custom columns were requested."
        ),
    )


class _LogsCountResponseSerializer(serializers.Serializer):
    count = serializers.IntegerField(help_text="Number of log entries matching the filters.")


class _LogsSparklineBucketSerializer(serializers.Serializer):
    time = serializers.CharField(help_text="Bucket start time (ISO 8601).")
    severity = serializers.CharField(
        required=False,
        help_text='Severity label when sparklineBreakdownBy="severity". Present only for severity-broken-down sparklines.',
    )
    service = serializers.CharField(
        required=False,
        help_text='Service name when sparklineBreakdownBy="service". Present only for service-broken-down sparklines.',
    )
    count = serializers.IntegerField(help_text="Number of log entries in the bucket.")
    bytes_uncompressed = serializers.IntegerField(
        required=False,
        help_text="Sum of uncompressed bytes for the bucket.",
    )


class _LogsServiceSeverityBreakdownSerializer(serializers.Serializer):
    debug = serializers.IntegerField()
    info = serializers.IntegerField()
    warn = serializers.IntegerField()
    error = serializers.IntegerField()


class _LogsServiceActiveRuleSerializer(serializers.Serializer):
    rule_id = serializers.UUIDField()
    rule_name = serializers.CharField()
    summary_string = serializers.CharField()


class _LogsServiceAggregateSerializer(serializers.Serializer):
    service_name = serializers.CharField(
        help_text='Service name, or "(no value)" / "(no service)" placeholder for unset entries.',
    )
    status = serializers.ChoiceField(
        required=False,
        choices=LogsServiceStatus.choices,
        help_text=(
            "ok, degraded (error rate of 5% or more), regressed or improved (error rate up or down by 1 pp and 2x), "
            "recovered (back under 5%), new (no baseline logs) or silent (baseline logs, none in the window)."
        ),
    )
    reason = serializers.CharField(
        required=False, help_text='Short reason for the status, e.g. "error rate 0.4% → 3.1%".'
    )
    error_rate_pct = serializers.FloatField(required=False, help_text="Error rate in percent, rounded to 1 decimal.")
    baseline_log_count = serializers.IntegerField(
        required=False, allow_null=True, help_text="Logs in the baseline. Null without one."
    )
    error_rate_delta_pp = serializers.FloatField(
        required=False, allow_null=True, help_text="Error rate change against the baseline, in percentage points."
    )
    log_count_change_pct = serializers.FloatField(
        required=False, allow_null=True, help_text="Log volume change against the baseline, in percent."
    )
    last_seen = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Latest log time (UTC). From the rollup, and for silent services, the start of the last 5-minute bucket.",
    )
    log_count = serializers.IntegerField(help_text="Total log entries from this service in the window.")
    error_count = serializers.IntegerField(
        help_text='Count of logs at severity "error" or "fatal".',
    )
    error_rate = serializers.FloatField(
        help_text="Pre-computed error_count / log_count, rounded to 4 decimals. Useful for ranking noisy services.",
    )
    volume_share_pct = serializers.FloatField(
        required=False,
        help_text="Share of total log volume in the window for this service (0–100).",
    )
    severity_breakdown = _LogsServiceSeverityBreakdownSerializer(
        required=False,
        help_text="Counts by coarse severity bucket (debug, info, warn, error+fatal).",
    )
    active_rules = _LogsServiceActiveRuleSerializer(
        many=True,
        required=False,
        help_text="Enabled sampling rules whose scope includes this service.",
    )


class _LogsServicesSparklineBucketSerializer(serializers.Serializer):
    time = serializers.CharField(help_text="Bucket start time (ISO 8601).")
    service_name = serializers.CharField()
    count = serializers.IntegerField()


class _LogsServicesSummarySerializer(serializers.Serializer):
    top_services_count = serializers.IntegerField(
        help_text="Number of top services included in the volume_share aggregate (up to 5).",
    )
    top_services_volume_share_pct = serializers.FloatField(
        help_text="Combined volume share (percent) of the top services by log_count.",
    )
    status_counts = serializers.DictField(
        required=False, child=serializers.IntegerField(), help_text="Service rows per status."
    )
    truncated = serializers.BooleanField(
        required=False, help_text="True when more services matched than `services` holds."
    )


class _LogsWindowSerializer(serializers.Serializer):
    current = serializers.DictField(
        child=serializers.CharField(), help_text="`from` and `to` of the queried window, ISO 8601 UTC."
    )
    baseline = serializers.DictField(
        child=serializers.CharField(), required=False, help_text="`from` and `to` of the baseline. Absent without one."
    )
    timezone = serializers.CharField(help_text="Always UTC.")


class _LogsNextStepSerializer(serializers.Serializer):
    tool = serializers.CharField(help_text="MCP tool to call next.")
    why = serializers.CharField(help_text="What the call answers.")
    query = serializers.DictField(help_text="Prefilled `query` for that tool.")
    baselineDateRange = serializers.DictField(
        required=False, help_text="Prefilled sibling `baselineDateRange` argument, for tools that take one."
    )


class _LogsServicesResponseSerializer(serializers.Serializer):
    services = _LogsServiceAggregateSerializer(
        many=True,
        help_text="Per-service aggregates, ordered by log_count descending. Capped at 10000 services.",
    )
    sparkline = _LogsServicesSparklineBucketSerializer(
        many=True,
        help_text=(
            "Time-bucketed counts broken down by service, for plotting volume over time. "
            "Covers only the top 25 services in this response; re-request with `serviceNames` "
            "to get sparklines for specific services."
        ),
    )
    total_services = serializers.IntegerField(
        help_text=(
            "True distinct service count for the window and filters, unaffected by the 10000-service "
            "cap on `services`. Greater than the length of `services` when the response is truncated."
        ),
    )
    summary = _LogsServicesSummarySerializer(
        required=False,
        help_text="Roll-up stats for the Services tab header.",
    )
    window = _LogsWindowSerializer(required=False, help_text="Absolute UTC bounds of the window and the baseline.")
    source = serializers.ChoiceField(  # type: ignore[assignment]
        required=False,
        choices=LogsServicesSource.choices,
        help_text="rollup: 5-minute rollup only. rollup+raw: rollup plus raw logs at unaligned window edges.",
    )
    next = _LogsNextStepSerializer(
        required=False, many=True, help_text="Prefilled follow-up calls for problem services."
    )


class _LogsPatternsBodySerializer(serializers.Serializer):
    dateRange = _DateRangeSerializer(
        required=False,
        help_text="Date range to mine patterns from. Defaults to last hour.",
    )
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=list,
        help_text="Filter by log severity levels before mining.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=list,
        help_text="Restrict mining to these service names.",
    )
    searchTerm = serializers.CharField(
        required=False, help_text="Full-text search term to filter log bodies before mining."
    )
    filterGroup = serializers.ListField(
        child=_LogPropertyFilterSerializer(),
        required=False,
        default=list,
        help_text="Property filters applied before mining. Same shape as the query-logs endpoint.",
    )
    personId = _person_scope_field("mining")
    sessionId = _session_scope_field("mining")


class _LogsPatternsRequestSerializer(serializers.Serializer):
    query = _LogsPatternsBodySerializer(help_text="The patterns query to execute.")


class _LogPatternExampleSerializer(serializers.Serializer):
    body = serializers.CharField(
        help_text=(
            "Original-message example. Body mining normalizes whitespace, extracts JSON message fields "
            "and truncates to the mining cap. Stored-pattern aggregation returns the raw body prefix, "
            "limited to 4096 Unicode characters."
        ),
    )
    severity_text = serializers.CharField(help_text='Severity of the sampled line, e.g. "info", "error".')
    service_name = serializers.CharField(help_text="Service that emitted the sampled line.")
    timestamp = serializers.CharField(help_text="ISO 8601 timestamp of the sampled line.")


class _LogPatternSerializer(serializers.Serializer):
    pattern = serializers.CharField(
        help_text=(
            'Log template with variable tokens masked, e.g. "Connected to <ip> in <num>ms". '
            "Body mining masks <timestamp>, <uuid>, <ip>, <hex>, <num>, plus <*> for word positions "
            "Drain found to vary. Stored patterns use the ingestion vocabulary instead: <N>, "
            "<TIMESTAMP>, <KLOGTIME>, <UUID>, <IP>, <HOST>, <HEX>, <ID>, <EMAIL>, <JSON_ARRAY>, and "
            "<JSON:keys> for a JSON body reduced to its key set."
        ),
    )
    count = serializers.IntegerField(
        help_text=(
            "Occurrences of this pattern within the sample. When `sampled` is true this is a sample "
            "count, not the full-window total — prefer `estimated_count` for display."
        ),
    )
    estimated_count = serializers.IntegerField(
        help_text=(
            "Estimated occurrences across the full window, extrapolated from the sample "
            "(`count / scanned_count * total_count`). Equals `count` when the window was not sampled."
        ),
    )
    volume_share_pct = serializers.FloatField(
        help_text=(
            "Share of the log volume this pattern represents (0–100). Measured over the sample when "
            "`sampled` is true, over every matching row otherwise."
        ),
    )
    error_count = serializers.IntegerField(
        help_text=(
            'Occurrences at severity "error" or "fatal". A sample count when `sampled` is true, so '
            "prefer `estimated_error_count` for display."
        ),
    )
    estimated_error_count = serializers.IntegerField(
        help_text=(
            "Estimated error/fatal occurrences across the full window, extrapolated from the sample. "
            "Equals `error_count` when the window was not sampled."
        ),
    )
    first_seen = serializers.CharField(
        help_text=(
            "ISO 8601 timestamp of the earliest occurrence. Taken from the sample when `sampled` is "
            "true, from every matching row otherwise."
        )
    )
    last_seen = serializers.CharField(
        help_text=(
            "ISO 8601 timestamp of the latest occurrence. Taken from the sample when `sampled` is "
            "true, from every matching row otherwise."
        )
    )
    examples = _LogPatternExampleSerializer(
        many=True,
        help_text=(
            "Up to 10 distinct sampled log lines that produced this pattern, with severity, "
            "service, and timestamp for display."
        ),
    )
    services = serializers.ListField(
        child=serializers.CharField(),
        help_text="Up to 4 distinct service names this pattern was observed in.",
    )
    sparkline = serializers.ListField(
        child=serializers.IntegerField(),
        help_text=(
            "Occurrences per time bucket, aligned index-for-index with the response's "
            "`sparkline_buckets`. When `sampled` is true these are extrapolated like `estimated_count` "
            "and show the volume shape over the window rather than exact tallies. Otherwise they are "
            "exact per-bucket counts."
        ),
    )
    severity_counts = serializers.DictField(
        child=serializers.IntegerField(),
        help_text=(
            'Occurrences keyed by lowercased severity ("trace" through "fatal"). Never extrapolated, '
            "because severity dominance is a proportion that scaling would not change. Sample counts "
            "when `sampled` is true, counts over every matching row otherwise."
        ),
    )
    match_regex = serializers.CharField(
        allow_null=True,
        help_text=(
            "RE2-safe regex over raw log bodies that matches lines of this pattern, compiled from "
            "the template and validated against the raw bodies of the pattern's own sampled rows "
            "before being offered. Null when the template lacks literal content or validation "
            "failed. Never trust an unvalidated predicate. Use with the message/regex log "
            "property filter."
        ),
    )
    match_literal = serializers.CharField(
        allow_null=True,
        help_text=(
            "Longest literal run in the template, for plain-text (icontains) filtering when "
            "`match_regex` is null. Null when the template has no usable literal content."
        ),
    )
    match_patterns = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        help_text="Exact canonical members of a stored-pattern group. Filter pattern IN these values AND pattern_version equals this group's version. Empty for body mining.",
    )
    pattern_version = serializers.IntegerField(
        allow_null=True,
        required=False,
        help_text="Version required by match_patterns. Null for body mining.",
    )


class _LogsPatternsSparklineBucketSerializer(serializers.Serializer):
    start = serializers.CharField(help_text="Bucket start (ISO 8601, inclusive).")
    end = serializers.CharField(help_text="Bucket end (ISO 8601, exclusive).")


class _LogsPatternsSourceSerializer(serializers.Serializer):
    source = serializers.ChoiceField(  # type: ignore[assignment]
        choices=["stored_patterns", "body_mining"],
        required=False,
        help_text="Whether counts come from stored-pattern aggregation or body masking and Drain3 mining.",
    )
    pattern_version = serializers.IntegerField(
        allow_null=True,
        required=False,
        help_text="Stored pattern version used. Null for body mining.",
    )
    fallback_reason = serializers.ChoiceField(
        choices=["flag_disabled", "insufficient_version_coverage", "empty_window", "comparison"],
        allow_null=True,
        required=False,
        help_text="Why body mining was used. Null for stored-pattern aggregation.",
    )
    pattern_coverage_pct = serializers.FloatField(
        allow_null=True,
        required=False,
        help_text="Percentage of all matching rows with a nonempty pattern at the selected version. Null for body mining.",
    )
    represented_count = serializers.IntegerField(
        allow_null=True,
        required=False,
        help_text="Exact rows represented by the returned stored-pattern groups. Null for body mining.",
    )
    remainder_count = serializers.IntegerField(
        allow_null=True,
        required=False,
        help_text="Matching rows outside returned groups, including other versions, unstamped rows and the long tail. Null for body mining.",
    )


class _LogsPatternsResponseSerializer(_LogsPatternsSourceSerializer):
    patterns = _LogPatternSerializer(
        many=True,
        help_text="Pattern groups ordered by count. Stored-pattern counts are exact; body-mining counts describe the sample.",
    )
    scanned_count = serializers.IntegerField(
        help_text="Rows scanned: the sample size for body mining, or the full matching count for stored-pattern aggregation.",
    )
    total_count = serializers.IntegerField(
        help_text=(
            "Total log rows matching the filters in the window, before sampling. Use with "
            "`scanned_count` to scale per-pattern counts when `sampled` is true."
        ),
    )
    sampled = serializers.BooleanField(
        help_text=(
            "True when the window held more rows than the sample cap, so patterns were mined from "
            "a deterministic, evenly-distributed sample rather than every matching row."
        ),
    )
    sample_coverage_pct = serializers.FloatField(
        help_text=(
            "Share of the window's log rows that were eligible for sampling (0–100). Below 100, "
            "the scan was bounded to evenly-spaced time slices across the window to keep the "
            "query within its execution budget; rows outside the slices could not appear in the sample."
        ),
    )
    sparkline_buckets = _LogsPatternsSparklineBucketSerializer(
        many=True,
        help_text=(
            "Time buckets that every pattern's `sparkline` aligns to. When the scan was bounded to "
            "time slices, the buckets are the slices themselves (evenly spaced, gaps between them "
            "were never eligible for sampling); otherwise they divide the window uniformly."
        ),
    )


class _LogsPatternsDiffBodySerializer(_LogsPatternsBodySerializer, PatternsDiffBodyFields):
    pass


class _LogsPatternsDiffRequestSerializer(serializers.Serializer):
    query = _LogsPatternsDiffBodySerializer(
        help_text=(
            "The patterns query for the current (foreground) window: date range plus any "
            "severity/service/search/property filters. The same filters are applied to the baseline window."
        ),
    )
    baselineDateRange = _DateRangeSerializer(
        required=False,
        help_text=(
            "Baseline window to compare against. Omit to default to the current window shifted "
            "back exactly one week, which absorbs daily and weekly log-volume cycles. Pass an "
            "explicit range to compare against a specific period, e.g. pre-deploy or pre-incident."
        ),
    )


class _LogPatternDiffEntrySerializer(PatternDiffEntryFields):
    classification = serializers.ChoiceField(
        choices=["new", "rate_shift", "gone", "unchanged"],
        help_text=(
            '"new": appears only in the current window and clears the novelty floor (at least ~1% '
            'volume share, or any error/fatal occurrences). "rate_shift": present in both windows '
            "with the per-second rate changed by at least 2x either way, backed by enough samples "
            'on both sides to trust the estimates. "gone": cleared the floor in the baseline but '
            'absent from the current window. "unchanged" means "no confident claim", not "provably '
            'identical" — sampled mining cannot prove a below-floor template is genuinely new or gone.'
        ),
    )
    rate_ratio = serializers.FloatField(
        allow_null=True,
        help_text=(
            "Current-window rate divided by baseline rate, both normalized per second so windows "
            "of different lengths compare fairly. 4.0 means 4x faster now; 0.25 means quartered. "
            "Null when the pattern is missing from either window."
        ),
    )
    pattern = _LogPatternSerializer(
        help_text=(
            "The mined pattern with full stats. Taken from the current window, or from the "
            'baseline window for "gone" entries. When template wobble split one message across '
            "several near-identical templates, this is the highest-volume representative and the "
            "entry's classification reflects their combined counts."
        ),
    )
    baseline_estimated_count = serializers.IntegerField(
        allow_null=True,
        help_text=(
            "Estimated occurrences across the baseline window (extrapolated like `estimated_count`). "
            "Null when the pattern was not seen in the baseline sample."
        ),
    )
    baseline_volume_share_pct = serializers.FloatField(
        allow_null=True,
        help_text="Share of the baseline sample this pattern represented (0-100). Null when absent from the baseline.",
    )


class _LogsPatternsDiffWindowSerializer(_LogsPatternsSourceSerializer):
    scanned_count = serializers.IntegerField(help_text="Log rows fed to the miner for this window (sample size).")
    total_count = serializers.IntegerField(help_text="Total log rows matching the filters in this window.")
    sampled = serializers.BooleanField(
        help_text="True when this window's counts are extrapolated from a sample rather than exact.",
    )
    sample_coverage_pct = serializers.FloatField(
        help_text="Share of this window's rows eligible for sampling (0-100); below 100 the scan was time-slice bounded.",
    )
    date_from = serializers.CharField(help_text="Resolved window start (ISO 8601, inclusive).")
    date_to = serializers.CharField(help_text="Resolved window end (ISO 8601, exclusive).")


class _LogsPatternsDiffResponseSerializer(PatternsDiffResponseFields):
    entries = _LogPatternDiffEntrySerializer(
        many=True,
        help_text=(
            'Classified diff entries, most interesting first: "new" (by estimated count), then '
            '"rate_shift" (by shift magnitude), then "gone", then "unchanged". A pattern in the '
            "baseline is matched to the current window by literal-content fingerprint, so a "
            "placeholder widening between runs does not read as one pattern vanishing and another appearing."
        ),
    )
    current = _LogsPatternsDiffWindowSerializer(help_text="Mining metadata for the current window.")
    baseline = _LogsPatternsDiffWindowSerializer(
        help_text=(
            "Mining metadata for the baseline window. Check `total_count` before trusting a wall "
            'of "new" entries: an empty or tiny baseline (e.g. logging only started this week) '
            "makes everything look new."
        ),
    )


class _LogsGroupByDimensionSerializer(serializers.Serializer):
    key = serializers.CharField(
        help_text=(
            'The key this dimension groups by — an attribute key (e.g. "session_id", "service.name") '
            'or, when source is "column", one of the top-level log fields: '
            '"severity_level", "service_name", "trace_id", "span_id", "pattern" (the masked message template).'
        ),
    )
    source = serializers.ChoiceField(  # type: ignore[assignment]  # field named `source` shadows DRF Field.source
        choices=list(GROUP_SOURCES),
        default="log",
        help_text=(
            'Where this dimension\'s key lives: "log" for log-level attributes, "resource" for '
            'resource-level attributes, "column" for top-level log fields.'
        ),
    )


class _LogsGroupByBodySerializer(serializers.Serializer):
    dateRange = _DateRangeSerializer(
        required=False,
        help_text="Date range to aggregate over. Defaults to last hour.",
    )
    severityLevels = serializers.ListField(
        child=serializers.ChoiceField(choices=["trace", "debug", "info", "warn", "error", "fatal"]),
        required=False,
        default=list,
        help_text="Filter by log severity levels before grouping.",
    )
    serviceNames = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        default=list,
        help_text="Restrict grouping to these service names.",
    )
    searchTerm = serializers.CharField(
        required=False, help_text="Full-text search term to filter log bodies before grouping."
    )
    filterGroup = serializers.ListField(
        child=_LogPropertyFilterSerializer(),
        required=False,
        default=list,
        help_text="Property filters applied before grouping. Same shape as the query-logs endpoint.",
    )
    groupBy = serializers.CharField(
        required=False,
        help_text=(
            'The key to group logs by — an attribute key (e.g. "session_id", "service.name") or, '
            'when groupBySource is "column", one of the top-level log fields: '
            '"severity_level", "service_name", "trace_id", "span_id", "pattern". Ignored when groupBys is provided.'
        ),
    )
    groupBySource = serializers.ChoiceField(
        choices=list(GROUP_SOURCES),
        default="log",
        help_text=(
            'Where the grouping key lives: "log" for log-level attributes, "resource" for '
            'resource-level attributes, "column" for top-level log fields. Ignored when groupBys is provided.'
        ),
    )
    groupBys = serializers.ListField(
        child=_LogsGroupByDimensionSerializer(),
        required=False,
        min_length=1,
        max_length=MAX_GROUP_DIMENSIONS,
        help_text=(
            "Ordered group-by dimensions to combine (a group is one combination of per-dimension "
            f"values), up to {MAX_GROUP_DIMENSIONS}. Takes precedence over groupBy/groupBySource; "
            "one of the two must be provided."
        ),
    )
    orderGroupsBy = serializers.ChoiceField(
        choices=list(ORDER_FIELDS),
        default="log_count",
        help_text=(
            'Aggregate to rank groups by (descending): "log_count" for the noisiest groups, '
            '"error_count" for the most failing, "last_seen" for the most recent.'
        ),
    )
    limit = serializers.IntegerField(
        required=False,
        default=DEFAULT_GROUP_LIMIT,
        min_value=1,
        max_value=MAX_GROUP_LIMIT,
        help_text=f"Maximum number of groups to return (top-N by orderGroupsBy). Defaults to {DEFAULT_GROUP_LIMIT}.",
    )
    personId = _person_scope_field("grouping")
    sessionId = _session_scope_field("grouping")


class _LogsGroupByRequestSerializer(serializers.Serializer):
    query = _LogsGroupByBodySerializer(help_text="The group-by query to execute.")


class _LogsGroupByGroupSerializer(serializers.Serializer):
    value = serializers.CharField(
        help_text="The first dimension's grouped value. Kept for single-dimension callers; prefer `values`."
    )
    values = serializers.ListField(
        child=serializers.CharField(),
        help_text="This group's values, one per requested dimension, in request order.",
    )
    log_count = serializers.IntegerField(help_text="Number of matching logs in this group.")
    error_count = serializers.IntegerField(
        help_text='Number of matching logs in this group at severity "error" or "fatal".',
    )
    first_seen = serializers.CharField(
        required=False, help_text="ISO 8601 timestamp of the earliest matching log in this group."
    )
    last_seen = serializers.CharField(help_text="ISO 8601 timestamp of the most recent matching log in this group.")


class _LogsGroupByResponseSerializer(serializers.Serializer):
    groups = _LogsGroupByGroupSerializer(
        many=True,
        help_text="Top groups ordered by the requested aggregate, descending. Capped at `limit`.",
    )
    total_groups = serializers.IntegerField(
        help_text="Total distinct group values matching the filters, before the top-N cap.",
    )
    total_logs = serializers.IntegerField(
        help_text="Total matching logs across all groups (rows without the grouping key are excluded).",
    )
    truncated = serializers.BooleanField(
        help_text="True when more groups matched than were returned (total_groups > groups length).",
    )


class _LogAttributeEntrySerializer(serializers.Serializer):
    name = serializers.CharField()
    propertyFilterType = serializers.CharField(
        help_text='Property filter type: "log_attribute" or "log_resource_attribute". Use this as the `type` field when filtering.',
    )
    matchedOn = serializers.ChoiceField(
        choices=["key", "value"],
        help_text='How the search query matched this row: "key" if the attribute key matched, "value" if a value matched.',
    )
    matchedValue = serializers.CharField(
        required=False,
        allow_null=True,
        help_text='Sample matching value — only set when matchedOn is "value".',
    )


class _LogsAttributesResponseSerializer(serializers.Serializer):
    results = _LogAttributeEntrySerializer(many=True, help_text="Available attribute keys matching the filters.")
    count = serializers.IntegerField(help_text="Total attribute keys matched (not paginated).")


class _LogAttributeValueSerializer(serializers.Serializer):
    id = serializers.CharField(help_text="Attribute value (used as the identifier).")
    name = serializers.CharField(help_text="Display name — currently identical to `id`.")
    count = serializers.IntegerField(
        required=False,
        help_text="Number of log records with this attribute value, scoped to the current date range, service, and resource filters.",
    )


class _LogsValuesResponseSerializer(serializers.Serializer):
    results = _LogAttributeValueSerializer(many=True, help_text="Distinct values observed for the requested attribute.")
    refreshing = serializers.BooleanField(
        help_text="Always false — reserved for future cached-value refresh signalling."
    )


class LogsViewSet(TeamAndOrgViewSetMixin, PydanticModelMixin, viewsets.ViewSet):
    scope_object = "logs"
    serializer_class = _FallbackSerializer
    _logs_api_slot: ConcurrencySlot | None = None

    def get_throttles(self) -> list[BaseThrottle]:
        # patterns_diff mines two windows per request (current + baseline), roughly doubling the
        # ClickHouse work of a single patterns query, so it uses the tighter ClickHouse-specific
        # throttles rather than the default per-project request limits.
        if self.action == "patterns_diff":
            return [ClickHouseBurstRateThrottle(), ClickHouseSustainedRateThrottle()]
        return super().get_throttles()

    def initial(self, request: Request, *args: Any, **kwargs: Any) -> None:
        super().initial(request, *args, **kwargs)
        if not isinstance(request.successful_authenticator, PersonalAPIKeyAuthentication):
            return
        try:
            self._logs_api_slot = get_logs_api_team_rate_limiter().use(team_id=self.team_id)
        except ConcurrencyLimitExceeded as error:
            logger.warning("logs_api_concurrency_limit_exceeded", team_id=self.team_id, detail=str(error))
            # wait sets a Retry-After header, so a polling client backs off instead of retrying the burst at once.
            raise Throttled(wait=1, detail=CONCURRENCY_LIMIT_USER_MESSAGE) from error
        except RedisError:
            # The cap protects ClickHouse capacity. A Redis outage must not also make the logs API fail.
            logger.exception("logs_api_concurrency_limiter_unavailable", team_id=self.team_id)

    def dispatch(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponseBase:
        # DRF skips finalize_response when the exception handler re-raises an error, so only a finally block
        # releases the slot on every path.
        try:
            return super().dispatch(request, *args, **kwargs)
        finally:
            if self._logs_api_slot is not None:
                try:
                    get_logs_api_team_rate_limiter().release(self._logs_api_slot)
                except RedisError:
                    # The slot expires after the limiter's ttl, so keep the response the query already produced.
                    logger.exception("logs_api_concurrency_slot_release_failed", team_id=self.team_id)
                self._logs_api_slot = None

    @staticmethod
    def _normalize_filter_group(filter_group: object) -> dict:
        """Normalize a flat filter array (from MCP) to the nested PropertyGroupFilter structure."""
        if isinstance(filter_group, list):
            if len(filter_group) > 0:
                return {"type": "AND", "values": [{"type": "AND", "values": filter_group}]}
            return {"type": "AND", "values": []}
        if isinstance(filter_group, dict):
            return filter_group
        return {"type": "AND", "values": []}

    @staticmethod
    def _filter_group_from_query_params(request: Request) -> PropertyGroupFilter | None:
        try:
            filter_group = json.loads(request.GET.get("filterGroup") or "null")
        except ValueError:
            return None
        if not isinstance(filter_group, dict | list) or not filter_group:
            return None
        try:
            return PropertyGroupFilter.model_validate(LogsViewSet._normalize_filter_group(filter_group))
        except ValidationError:
            return None

    @staticmethod
    def _require_dict_query(query_data: object) -> None:
        """Guard against a non-object `query` field crashing on the first `.get()` call below."""
        if not isinstance(query_data, dict):
            raise ParseError("query must be an object")

    def _filtered_logs_query(self, query_data: dict) -> LogsQuery:
        """The shared date-range + filters subset of LogsQuery used by aggregation actions."""
        date_range_data = query_data.get("dateRange")
        return LogsQuery(
            # The body serializers document dateRange as optional, so an absent range must
            # default rather than 400 (get_model rejects None).
            dateRange=self.get_model(date_range_data, DateRange) if date_range_data else DateRange(date_from="-1h"),
            # A null list in the body must default like an absent one instead of failing validation.
            severityLevels=query_data.get("severityLevels") or [],
            serviceNames=query_data.get("serviceNames") or [],
            searchTerm=query_data.get("searchTerm", None),
            filterGroup=self._normalize_filter_group(query_data.get("filterGroup", None)),
            # Patterns and Group are modes of the same viewer, so they inherit its scope. Dropping
            # these would mine or aggregate the whole project and label the result one session.
            personId=query_data.get("personId", None),
            sessionId=query_data.get("sessionId", None),
        )

    @staticmethod
    def _filter_analytics_props(query_data: dict) -> dict:
        """The filter-shape properties every logs aggregation action reports."""
        return {
            "has_search_term": bool(query_data.get("searchTerm")),
            "has_filter_group": bool(query_data.get("filterGroup")),
            "severity_levels_count": len(query_data.get("severityLevels") or []),
            "service_names_count": len(query_data.get("serviceNames") or []),
        }

    @extend_schema(request=_LogsQueryRequestSerializer, responses={200: _LogsQueryResponseSerializer})
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"])
    def query(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", None)
        if query_data is None:
            return Response({"error": "No query provided"}, status=status.HTTP_400_BAD_REQUEST)
        self._require_dict_query(query_data)

        live_logs_checkpoint = query_data.get("liveLogsCheckpoint", None)
        after_cursor = query_data.get("after", None)
        date_range = self.get_model(query_data.get("dateRange"), DateRange)

        custom_columns = query_data.get("customColumns") or []
        if len(custom_columns) > MAX_CUSTOM_COLUMNS:
            return Response(
                {"error": f"Too many custom columns: {len(custom_columns)} (max {MAX_CUSTOM_COLUMNS})"},
                status=status.HTTP_400_BAD_REQUEST,
            )

        order_by = query_data.get("orderBy")
        # Default to latest instead of erroring on invalid order_by
        if order_by not in (LogsOrderBy.EARLIEST, LogsOrderBy.LATEST):
            order_by = LogsOrderBy.LATEST
        # When using cursor pagination, narrow the date range based on the cursor timestamp.
        # This allows time-slicing optimization to work on progressively smaller ranges
        # as the user pages through results.
        if after_cursor:
            try:
                cursor = json.loads(base64.b64decode(after_cursor).decode("utf-8"))
                cursor_ts = dt.datetime.fromisoformat(cursor["timestamp"])
                if order_by == LogsOrderBy.EARLIEST:
                    # For "earliest" ordering, we're looking for logs AFTER the cursor
                    date_range = DateRange(
                        date_from=cursor_ts.isoformat(),
                        date_to=date_range.date_to,
                    )
                else:
                    # For "latest" ordering (default), we're looking for logs BEFORE the cursor
                    date_range = DateRange(
                        date_from=date_range.date_from,
                        date_to=cursor_ts.isoformat(),
                    )
            except (KeyError, ValueError, json.JSONDecodeError):
                pass  # Invalid cursor format, continue with original date range

        paging = _LogsBodyLimitSerializer(data=query_data)
        paging.is_valid(raise_exception=True)
        limit = paging.validated_data.get("limit")
        requested_limit = min(_LOGS_QUERY_SERVER_DEFAULT_LIMIT if limit is None else limit, _LOGS_QUERY_MAX_LIMIT)
        logs_query_params = {
            "dateRange": date_range,
            "severityLevels": query_data.get("severityLevels", []),
            "serviceNames": query_data.get("serviceNames", []),
            "orderBy": order_by,
            "searchTerm": query_data.get("searchTerm", None),
            "filterGroup": self._normalize_filter_group(query_data.get("filterGroup", None)),
            "resourceFingerprint": query_data.get("resourceFingerprint", None),
            "personId": query_data.get("personId", None),
            "sessionId": query_data.get("sessionId", None),
            "limit": requested_limit + 1,  # Fetch limit plus 1 to see if theres another page
            "excludeAttributes": query_data.get("excludeAttributes", False),
            "customColumns": custom_columns,
        }
        if live_logs_checkpoint:
            logs_query_params["liveLogsCheckpoint"] = live_logs_checkpoint
        if after_cursor:
            logs_query_params["after"] = after_cursor
        query = LogsQuery(**logs_query_params)
        analytics_props = get_request_analytics_properties(request)

        def make_runner(date_range: DateRange) -> LogsQueryRunner:
            return LogsQueryRunner(LogsQuery(**{**query.model_dump(), "dateRange": date_range}), self.team)

        # Skip time-slicing for live tailing - we're always only looking at the most recent 1-2 minutes
        # Note: cursor pagination no longer skips time-slicing because we narrow the date range
        # to end at the cursor timestamp, allowing time-slicing to work on the remaining range.
        try:
            # Replay asks for session logs on every recording open, and most of those teams send no logs.
            if query.sessionId and not team_has_logs(self.team, cache_negative=True):
                results: list[Any] = []
            elif live_logs_checkpoint:
                response = LogsQueryRunner(query, self.team).run(
                    ExecutionMode.CALCULATE_BLOCKING_ALWAYS, analytics_props=analytics_props
                )
                results = list(response.results)
            else:
                results = list(
                    time_sliced_results(
                        runner=LogsQueryRunner(query, self.team),
                        order_by_earliest=order_by == LogsOrderBy.EARLIEST,
                        make_runner=make_runner,
                        analytics_props=analytics_props,
                    )
                )
        except QueryError as e:
            # A bad custom-column expression is re-raised by the runner as QueryError; keep it a clean 400.
            return Response({"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)
        has_more = len(results) > requested_limit
        results = results[:requested_limit]  # Rm the +1 we used to check for another page

        # Generate cursor for next page
        next_cursor = None
        if has_more and results:
            last_result = results[-1]
            cursor_data = {
                "timestamp": last_result["timestamp"].isoformat(),
                "uuid": last_result["uuid"],
            }
            next_cursor = base64.b64encode(json.dumps(cursor_data).encode("utf-8")).decode("utf-8")

        if not live_logs_checkpoint:
            event_properties: dict[str, object] = {
                "results_count": len(results),
                "has_more": has_more,
                "has_search_term": bool(query_data.get("searchTerm")),
                "has_filter_group": bool(query_data.get("filterGroup")),
                "severity_levels_count": len(query_data.get("severityLevels") or []),
                "service_names_count": len(query_data.get("serviceNames") or []),
                "is_paginated": bool(after_cursor),
            }
            if results:
                # This endpoint serves the app, API keys, MCP and other integrations, so the property covers all of them.
                event_properties["$set_once"] = {"first_used_logs_at": timezone.now().isoformat()}
            report_user_action(
                request.user,
                "logs query executed",
                event_properties,
                team=self.team,
                request=request,
            )

        return Response(
            {
                "query": query,
                "results": results,
                "hasMore": has_more,
                "nextCursor": next_cursor,
                "maxExportableLogs": LOGS_MAX_EXPORT_ROWS,
                "columns": [canonical_key(c) for c in custom_columns] or None,
            },
            status=200,
        )

    @extend_schema(
        request=_LogsSparklineRequestSerializer,
        responses={200: _LogsSparklineBucketSerializer(many=True)},
    )
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"])
    def sparkline(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        date_range_data = query_data.get("dateRange")
        date_range = self.get_model(date_range_data, DateRange) if date_range_data else DateRange(date_from="-1h")

        query = LogsQuery(
            dateRange=date_range,
            severityLevels=query_data.get("severityLevels", []),
            serviceNames=query_data.get("serviceNames", []),
            searchTerm=query_data.get("searchTerm", None),
            filterGroup=self._normalize_filter_group(query_data.get("filterGroup", None)),
            resourceFingerprint=query_data.get("resourceFingerprint", None),
            personId=query_data.get("personId", None),
            sessionId=query_data.get("sessionId", None),
            sparklineBreakdownBy=query_data.get("sparklineBreakdownBy"),
            sparklineRankBy=query_data.get("sparklineRankBy"),
        )

        runner = SparklineQueryRunner(team=self.team, query=query)
        response = runner.run(
            ExecutionMode.CALCULATE_BLOCKING_ALWAYS,
            analytics_props=get_request_analytics_properties(request),
        )
        assert isinstance(response, LogsQueryResponse | CachedLogsQueryResponse)

        report_user_action(
            request.user,
            "logs sparkline queried",
            {
                "has_search_term": bool(query_data.get("searchTerm")),
                "has_filter_group": bool(query_data.get("filterGroup")),
                "severity_levels_count": len(query_data.get("severityLevels") or []),
                "service_names_count": len(query_data.get("serviceNames") or []),
                "breakdown_by": query_data.get("sparklineBreakdownBy"),
            },
            team=self.team,
            request=request,
        )

        return Response(response.results, status=status.HTTP_200_OK)

    @extend_schema(request=_LogsFacetValuesRequestSerializer, responses={200: _LogsFacetValuesResponseSerializer})
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"])
    def facet_values(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        facet_field = query_data.get("facetField")
        facet_resource_attribute = query_data.get("facetResourceAttribute")
        facet_attribute = query_data.get("facetAttribute")
        if sum(1 for target in (facet_field, facet_resource_attribute, facet_attribute) if target) != 1:
            raise ParseError("Provide exactly one of facetField, facetResourceAttribute or facetAttribute")
        if facet_field and facet_field not in FACET_FIELDS:
            raise ParseError(f"facetField must be one of {sorted(FACET_FIELDS)}")

        date_range_data = query_data.get("dateRange")
        date_range = self.get_model(date_range_data, DateRange) if date_range_data else DateRange(date_from="-1h")

        query = LogsQuery(
            dateRange=date_range,
            severityLevels=query_data.get("severityLevels", []),
            serviceNames=query_data.get("serviceNames", []),
            searchTerm=query_data.get("searchTerm", None),
            filterGroup=self._normalize_filter_group(query_data.get("filterGroup", None)),
            personId=query_data.get("personId", None),
            sessionId=query_data.get("sessionId", None),
        )

        runner = LogFacetValuesQueryRunner(
            team=self.team,
            query=query,
            facet_field=facet_field or None,
            facet_resource_attribute=facet_resource_attribute or None,
            facet_attribute=facet_attribute or None,
            facet_search=query_data.get("facetSearch"),
        )
        response = runner.run(
            ExecutionMode.CALCULATE_BLOCKING_ALWAYS,
            analytics_props=get_request_analytics_properties(request),
        )
        assert isinstance(response, LogsQueryResponse | CachedLogsQueryResponse)
        return Response({"results": response.results}, status=status.HTTP_200_OK)

    @extend_schema(request=_LogsCountRequestSerializer, responses={200: _LogsCountResponseSerializer})
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"])
    def count(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        query = self._filtered_logs_query(query_data)

        runner = CountQueryRunner(team=self.team, query=query)
        response = runner.run(
            ExecutionMode.CALCULATE_BLOCKING_ALWAYS,
            analytics_props=get_request_analytics_properties(request),
        )
        assert isinstance(response, LogsQueryResponse | CachedLogsQueryResponse)

        report_user_action(
            request.user,
            "logs count queried",
            self._filter_analytics_props(query_data),
            team=self.team,
            request=request,
        )

        return Response(response.results, status=status.HTTP_200_OK)

    @extend_schema(request=_LogsImpactRequestSerializer, responses={200: _LogsImpactResponseSerializer})
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"])
    def impact(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        query = self._filtered_logs_query(query_data)

        runner = ImpactQueryRunner(team=self.team, query=query)
        response = runner.run(
            ExecutionMode.CALCULATE_BLOCKING_ALWAYS,
            analytics_props=get_request_analytics_properties(request),
        )
        assert isinstance(response, LogsQueryResponse | CachedLogsQueryResponse)

        report_user_action(
            request.user,
            "logs impact queried",
            self._filter_analytics_props(query_data),
            team=self.team,
            request=request,
        )

        return Response(response.results, status=status.HTTP_200_OK)

    @extend_schema(
        request=_LogsCountRangesRequestSerializer,
        responses={200: _LogsCountRangesResponseSerializer},
    )
    # nosemgrep: api-path-underscore -- shipped public API path, a rename breaks clients
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"], url_path="count-ranges")
    def count_ranges(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        date_range_data = query_data.get("dateRange")
        date_range = self.get_model(date_range_data, DateRange) if date_range_data else DateRange(date_from="-1h")

        target_buckets = query_data.get("targetBuckets", DEFAULT_TARGET_BUCKETS)

        query = LogsQuery(
            dateRange=date_range,
            severityLevels=query_data.get("severityLevels", []),
            serviceNames=query_data.get("serviceNames", []),
            searchTerm=query_data.get("searchTerm", None),
            filterGroup=self._normalize_filter_group(query_data.get("filterGroup", None)),
        )

        runner = CountRangesQueryRunner(team=self.team, query=query, target_buckets=target_buckets)
        response = runner.run(
            ExecutionMode.CALCULATE_BLOCKING_ALWAYS,
            analytics_props=get_request_analytics_properties(request),
        )
        assert isinstance(response, LogsQueryResponse | CachedLogsQueryResponse)

        report_user_action(
            request.user,
            "logs count ranges queried",
            {
                "target_buckets": target_buckets,
                "has_search_term": bool(query_data.get("searchTerm")),
                "has_filter_group": bool(query_data.get("filterGroup")),
                "severity_levels_count": len(query_data.get("severityLevels") or []),
                "service_names_count": len(query_data.get("serviceNames") or []),
            },
            team=self.team,
            request=request,
        )

        return Response(response.results, status=status.HTTP_200_OK)

    @extend_schema(request=_LogsServicesRequestSerializer, responses={200: _LogsServicesResponseSerializer})
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"])
    def services(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        query = LogsQuery(
            dateRange=self.get_model(query_data.get("dateRange"), DateRange),
            severityLevels=query_data.get("severityLevels", []),
            serviceNames=query_data.get("serviceNames", []),
            searchTerm=query_data.get("searchTerm", None),
            filterGroup=self._normalize_filter_group(query_data.get("filterGroup", None)),
        )

        compare = query_data.get("compare") or "none"
        if compare not in COMPARE_MODES:
            return Response(
                {"error": f"compare must be one of {', '.join(COMPARE_MODES)}"}, status=status.HTTP_400_BAD_REQUEST
            )
        if not isinstance(query_data.get("environment") or "", str):
            return Response({"error": "environment must be a string"}, status=status.HTTP_400_BAD_REQUEST)
        baseline_data = request.data.get("baselineDateRange")
        runner = ServicesQueryRunner(
            team=self.team,
            query=query,
            service_name_search=query_data.get("serviceNameSearch") or None,
            environment=query_data.get("environment") or None,
            compare=compare,
            baseline_date_range=self.get_model(baseline_data, DateRange) if baseline_data else None,
        )
        response = runner.run(
            ExecutionMode.CALCULATE_BLOCKING_ALWAYS,
            analytics_props=get_request_analytics_properties(request),
        )
        assert isinstance(response, LogsQueryResponse | CachedLogsQueryResponse)

        report_user_action(
            request.user,
            "logs services queried",
            {
                "services_count": len(response.results.get("services", []))
                if isinstance(response.results, dict)
                else 0,
                "has_search_term": bool(query_data.get("searchTerm")),
                "severity_levels_count": len(query_data.get("severityLevels") or []),
                "service_names_count": len(query_data.get("serviceNames") or []),
            },
            team=self.team,
            request=request,
        )

        return Response(response.results, status=status.HTTP_200_OK)

    @extend_schema(request=_LogsPatternsRequestSerializer, responses={200: _LogsPatternsResponseSerializer})
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"])
    def patterns(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        query = self._filtered_logs_query(query_data)

        runner = PatternsQueryRunner(
            team=self.team, query=query, user=request.user if isinstance(request.user, User) else None
        )
        response = runner.run(
            ExecutionMode.CALCULATE_BLOCKING_ALWAYS,
            analytics_props=get_request_analytics_properties(request),
        )
        assert isinstance(response, LogsQueryResponse | CachedLogsQueryResponse)

        report_user_action(
            request.user,
            "logs patterns queried",
            {
                "patterns_count": len(response.results.get("patterns", []))
                if isinstance(response.results, dict)
                else 0,
                "sampled": response.results.get("sampled") if isinstance(response.results, dict) else None,
                "source": response.results.get("source") if isinstance(response.results, dict) else None,
                "pattern_version": response.results.get("pattern_version")
                if isinstance(response.results, dict)
                else None,
                "fallback_reason": response.results.get("fallback_reason")
                if isinstance(response.results, dict)
                else None,
                "has_search_term": bool(query_data.get("searchTerm")),
                "severity_levels_count": len(query_data.get("severityLevels") or []),
                "service_names_count": len(query_data.get("serviceNames") or []),
            },
            team=self.team,
            request=request,
        )

        return Response(response.results, status=status.HTTP_200_OK)

    @extend_schema(request=_LogsPatternsDiffRequestSerializer, responses={200: _LogsPatternsDiffResponseSerializer})
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"], url_path="patterns_diff")
    def patterns_diff(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        query = self._filtered_logs_query(query_data)
        baseline_date_range = (
            self.get_model(request.data["baselineDateRange"], DateRange)
            if request.data.get("baselineDateRange")
            else None
        )

        options = PatternsDiffBodyFields(data={"limit": query_data["limit"]} if "limit" in query_data else {})
        options.is_valid(raise_exception=True)
        results = run_patterns_diff(
            self.team,
            query,
            baseline_date_range,
            user=request.user if isinstance(request.user, User) else None,
            limit=options.validated_data.get("limit"),
            # The comparison runs several queries in sequence. End it before the concurrency slot's ttl, so the
            # slot cannot expire while the request still queries ClickHouse.
            deadline=monotonic() + get_logs_api_team_rate_limiter().ttl - LOGS_API_SLOT_TTL_MARGIN_SECONDS,
        )

        report_user_action(
            request.user,
            "logs patterns diff queried",
            {
                "entries_count": len(results["entries"]),
                "changed_count": sum(1 for e in results["entries"] if e["classification"] != "unchanged"),
                "auto_baseline": baseline_date_range is None,
                "has_search_term": bool(query_data.get("searchTerm")),
                "severity_levels_count": len(query_data.get("severityLevels") or []),
                "service_names_count": len(query_data.get("serviceNames") or []),
            },
            team=self.team,
            request=request,
        )

        return Response(results, status=status.HTTP_200_OK)

    @extend_schema(request=_LogsGroupByRequestSerializer, responses={200: _LogsGroupByResponseSerializer})
    # nosemgrep: api-path-underscore -- shipped public API path, a rename breaks clients
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"], url_path="group-by")
    def group_by(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", {})
        self._require_dict_query(query_data)

        query = self._filtered_logs_query(query_data)

        raw_dimensions = query_data.get("groupBys")
        if raw_dimensions is not None:
            # The dimension serializer is the request contract; running it here keeps the
            # enforced shape (required key, source vocabulary, defaults) identical to the
            # published schema instead of hand-rolling a second definition.
            dimension_serializer = _LogsGroupByDimensionSerializer(data=raw_dimensions, many=True)
            if not dimension_serializer.is_valid():
                return Response({"error": str(dimension_serializer.errors)}, status=status.HTTP_400_BAD_REQUEST)
            group_bys = [(d["key"], d["source"]) for d in dimension_serializer.validated_data]
        else:
            group_bys = [(query_data.get("groupBy", ""), query_data.get("groupBySource", "log"))]

        paging = _LogsBodyLimitSerializer(data=query_data)
        paging.is_valid(raise_exception=True)
        limit = paging.validated_data.get("limit")

        try:
            runner = LogsGroupByQueryRunner(
                team=self.team,
                query=query,
                group_bys=group_bys,
                order_groups_by=query_data.get("orderGroupsBy", "log_count"),
                group_limit=DEFAULT_GROUP_LIMIT if limit is None else limit,
            )
        except (ValueError, TypeError) as e:
            return Response({"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)

        response = runner.run(
            ExecutionMode.RECENT_CACHE_CALCULATE_BLOCKING_IF_STALE,
            analytics_props=get_request_analytics_properties(request),
        )
        assert isinstance(response, LogsQueryResponse | CachedLogsQueryResponse)

        results = response.results if isinstance(response.results, dict) else {}
        report_user_action(
            request.user,
            "logs group by queried",
            {
                "group_by_source": group_bys[0][1],
                "group_dimensions": len(group_bys),
                "order_groups_by": query_data.get("orderGroupsBy", "log_count"),
                "groups_count": len(results.get("groups", [])),
                "truncated": results.get("truncated"),
                "has_search_term": bool(query_data.get("searchTerm")),
                "severity_levels_count": len(query_data.get("severityLevels") or []),
                "service_names_count": len(query_data.get("serviceNames") or []),
            },
            team=self.team,
            request=request,
        )

        return Response(response.results, status=status.HTTP_200_OK)

    @extend_schema(parameters=[_LogsAttributesQuerySerializer], responses={200: _LogsAttributesResponseSerializer})
    @action(detail=False, methods=["GET"], required_scopes=["logs:read"])
    def attributes(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        search = request.GET.get("search", "")
        search_values = request.GET.get("search_values", "false").lower() == "true"
        limit = request.GET.get("limit", 100)
        offset = request.GET.get("offset", 0)

        try:
            dateRange = self.get_model(json.loads(request.GET.get("dateRange", "{}")), DateRange)
        except (json.JSONDecodeError, ValidationError, ValueError):
            # Default to last hour if dateRange is malformed
            dateRange = DateRange(date_from="-1h")
        # Flat params let clients that cannot send a JSON query param (the generated frontend client) scope the window.
        if "dateRange" not in request.GET and (request.GET.get("date_from") or request.GET.get("date_to")):
            dateRange = DateRange(date_from=request.GET.get("date_from"), date_to=request.GET.get("date_to"))

        try:
            serviceNames = json.loads(request.GET.get("serviceNames", "[]"))
        except json.JSONDecodeError:
            serviceNames = []
        filterGroup = self._filter_group_from_query_params(request)

        attributeType = request.GET.get("attribute_type", "log")
        # I don't know why went with 'log' and 'resource' not 'log_attribute' and 'log_resource_attribute'
        # like the property type, but annoyingly it's hard to update this in clickhouse so we're stuck with it for now
        if attributeType not in ["log", "resource"]:
            attributeType = "log"

        try:
            limit = int(limit)
        except ValueError:
            limit = 100

        try:
            offset = int(offset)
        except ValueError:
            offset = 0

        attribute_keys = list(dict.fromkeys(k.strip() for k in request.GET.get("keys", "").split(",") if k.strip()))
        if len(attribute_keys) > MAX_ATTRIBUTE_KEYS:
            return Response(
                {"error": f"At most {MAX_ATTRIBUTE_KEYS} keys are allowed."}, status=status.HTTP_400_BAD_REQUEST
            )

        query = LogAttributesQuery(
            dateRange=dateRange,
            attributeType=attributeType,
            attributeKeys=attribute_keys or None,
            search=search,
            searchValues=search_values,
            limit=limit,
            offset=offset,
            serviceNames=serviceNames,
            filterGroup=filterGroup,
        )

        runner = LogAttributesQueryRunner(team=self.team, query=query)

        try:
            result = runner.calculate()
        except (QueryError, ExposedCHQueryError) as e:
            # A user query error (HogQL or ClickHouse) becomes a clean 400 the filter can show.
            return Response({"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)
        return Response(
            {
                "results": [r.model_dump(exclude_none=True) for r in result.results],
                "count": result.count,
            },
            status=status.HTTP_200_OK,
        )

    @extend_schema(parameters=[_LogsValuesQuerySerializer], responses={200: _LogsValuesResponseSerializer})
    @action(detail=False, methods=["GET"], required_scopes=["logs:read"])
    def values(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        with (
            PROPERTY_VALUES_DURATION.labels(endpoint_type="log").time(),
            tracer.start_as_current_span("logs_api_property_values") as span,
        ):
            search = request.GET.get("value", "")
            limit = request.GET.get("limit", 100)
            offset = request.GET.get("offset", 0)
            attributeKey = request.GET.get("key", "")

            span.set_attribute("team_id", self.team.pk)
            span.set_attribute("property_key", attributeKey)
            span.set_attribute("has_value_filter", bool(search))

            if not attributeKey:
                return Response("key is required", status=status.HTTP_400_BAD_REQUEST)

            try:
                dateRange = self.get_model(json.loads(request.GET.get("dateRange", "{}")), DateRange)
            except (json.JSONDecodeError, ValidationError, ValueError):
                # Default to last hour if dateRange is malformed
                dateRange = DateRange(date_from="-1h")

            try:
                serviceNames = json.loads(request.GET.get("serviceNames", "[]"))
            except json.JSONDecodeError:
                serviceNames = []
            filterGroup = self._filter_group_from_query_params(request)

            attributeType = request.GET.get("attribute_type", "log")
            # I don't know why went with 'log' and 'resource' not 'log_attribute' and 'log_resource_attribute'
            # like the property type, but annoyingly it's hard to update this in clickhouse so we're stuck with it for now
            if attributeType not in ["log", "resource"]:
                attributeType = "log"

            span.set_attribute("attribute_type", attributeType)

            try:
                limit = int(limit)
            except ValueError:
                limit = 100

            try:
                offset = int(offset)
            except ValueError:
                offset = 0

            query = LogValuesQuery(
                dateRange=dateRange,
                attributeKey=attributeKey,
                attributeType=attributeType,
                search=search,
                limit=limit,
                offset=offset,
                serviceNames=serviceNames,
                filterGroup=filterGroup,
            )

            runner = LogValuesQueryRunner(team=self.team, query=query)

            try:
                result = runner.calculate()
            except (QueryError, ExposedCHQueryError) as e:
                # A user query error (HogQL or ClickHouse) becomes a clean 400 the filter can show.
                return Response({"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)
            span.set_attribute("result_count", len(result.results))
            return Response(
                {"results": [r.model_dump() for r in result.results], "refreshing": False},
                status=status.HTTP_200_OK,
            )

    @extend_schema(responses={200: OpenApiTypes.OBJECT})
    @action(detail=False, methods=["GET"], required_scopes=["logs:read"])
    def has_logs(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        has_logs = team_has_logs(self.team)

        report_user_action(
            request.user,
            "logs has_logs checked",
            {"has_logs": has_logs},
            team=self.team,
            request=request,
        )

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

    @extend_schema(responses={201: OpenApiTypes.OBJECT})
    @action(detail=False, methods=["POST"], required_scopes=["logs:read"])
    def export(self, request: Request, *args, **kwargs) -> Response:
        tag_queries(product=Product.LOGS, feature=Feature.QUERY)
        query_data = request.data.get("query", None)
        if query_data is None:
            return Response({"error": "No query provided"}, status=status.HTTP_400_BAD_REQUEST)
        self._require_dict_query(query_data)

        custom_columns = query_data.get("customColumns") or []
        if len(custom_columns) > MAX_CUSTOM_COLUMNS:
            return Response(
                {"error": f"Too many custom columns: {len(custom_columns)} (max {MAX_CUSTOM_COLUMNS})"},
                status=status.HTTP_400_BAD_REQUEST,
            )

        columns = request.data.get("columns") or []
        filename = self._generate_export_filename(query_data)

        asset = ExportedAsset.objects.create(
            team=self.team,
            export_format=ExportedAsset.ExportFormat.CSV,
            export_context={
                "source": {**query_data, "kind": "LogsQuery", "limit": LOGS_MAX_EXPORT_ROWS},
                "columns": columns,
                "filename": filename,
                "row_limit": LOGS_MAX_EXPORT_ROWS,
            },
            created_by=request.user if isinstance(request.user, User) else None,
        )

        export_asset.delay(asset.id)

        report_user_action(
            request.user,
            "logs export requested",
            {
                "export_id": asset.id,
                "columns_count": len(columns),
                "has_search_term": bool(query_data.get("searchTerm")),
                "service_names_count": len(query_data.get("serviceNames") or []),
            },
            team=self.team,
            request=request,
        )

        return Response(
            {
                "id": asset.id,
                "export_format": asset.export_format,
                "created_at": asset.created_at,
                "has_content": asset.has_content,
                "filename": asset.filename,
            },
            status=status.HTTP_201_CREATED,
        )

    def _generate_export_filename(self, query_data: dict) -> str:
        service_names = query_data.get("serviceNames") or []
        if len(service_names) == 1:
            service_part = re.sub(r"[^a-zA-Z0-9_-]", "-", service_names[0])[:50]
        elif len(service_names) > 1:
            service_part = f"{len(service_names)}-services"
        else:
            service_part = "all-services"

        date_range = query_data.get("dateRange", {})
        date_from = date_range.get("date_from", "")[:10] if date_range.get("date_from") else ""
        date_to = date_range.get("date_to", "")[:10] if date_range.get("date_to") else ""
        if date_from and date_to:
            date_part = f"{date_from}-to-{date_to}"
        elif date_from:
            date_part = f"from-{date_from}"
        else:
            date_part = timezone.now().strftime("%Y-%m-%d")

        return f"logs-{service_part}-{date_part}"