Skip to content

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

feat(mcp): accept object date ranges on tracing tools and add pattern diff first-seen (#119972)

Daniel Visca845ae60a75e2
diff --git a/products/logs/backend/pattern_diff.py b/products/logs/backend/pattern_diff.py
index eb34d48ee7c2..9ffb7566f82d 100644
--- a/products/logs/backend/pattern_diff.py
+++ b/products/logs/backend/pattern_diff.py
@@ -1,17 +1,29 @@
import datetime as dt
+from collections.abc import Callable
from typing import TYPE_CHECKING
from posthog.schema import DateRange, LogsQuery
+from posthog.hogql import ast
+from posthog.hogql.parser import parse_expr, parse_select
+from posthog.hogql.query import execute_hogql_query
+
+from posthog.clickhouse.client.connection import Workload
+from posthog.errors import CHQueryErrorTooManyBytes
+from posthog.exceptions import ClickHouseQueryTimeOut
from posthog.hogql_queries.query_runner import ExecutionMode
+from products.logs.backend.agent_window import utc_iso, window_echo
from products.logs.backend.log_patterns import ERROR_SEVERITIES, _env, pattern_fingerprint
+from products.logs.backend.logs_query_runner import fail_fast_aggregate_settings
from products.logs.backend.patterns_query_runner import PatternsQueryRunner
if TYPE_CHECKING:
- from posthog.models import Team
+ from posthog.models import Team, User
_BASELINE_OFFSET = dt.timedelta(days=7)
+FIRST_SEEN_LOOKBACK = dt.timedelta(days=14)
+_FIRST_SEEN_MAX_MEMBERS = 5000
def _rate(estimated_count: float, window: tuple[dt.datetime, dt.datetime]) -> float:
@@ -23,13 +35,38 @@ def _has_error_severity(pattern: dict) -> bool:
return any(severity in ERROR_SEVERITIES for severity in pattern.get("severity_counts", {}))
-def _group_by_fingerprint(patterns: list[dict]) -> dict[str, list[dict]]:
+def _fingerprint_key(pattern: dict) -> str:
+ return pattern_fingerprint(pattern["pattern"])
+
+
+def _group_by_key(patterns: list[dict], key: Callable[[dict], str]) -> dict[str, list[dict]]:
grouped: dict[str, list[dict]] = {}
for pattern in patterns:
- grouped.setdefault(pattern_fingerprint(pattern["pattern"]), []).append(pattern)
+ grouped.setdefault(key(pattern), []).append(pattern)
return grouped
+def stored_pattern_keys(current: list[dict], baseline: list[dict]) -> Callable[[dict], str]:
+ parent: dict[str, str] = {}
+
+ def find(member: str) -> str:
+ while parent.setdefault(member, member) != member:
+ parent[member] = parent[parent[member]]
+ member = parent[member]
+ return member
+
+ for group in (*current, *baseline):
+ roots = {find(member) for member in group["match_patterns"]}
+ root = min(roots)
+ for other in roots:
+ parent[other] = root
+
+ def key(pattern: dict) -> str:
+ return find(pattern["match_patterns"][0])
+
+ return key
+
+
def _representative(group: list[dict]) -> dict:
return max(group, key=lambda p: p["estimated_count"])
@@ -50,6 +87,7 @@ def diff_patterns(
*,
current_window: tuple[dt.datetime, dt.datetime],
baseline_window: tuple[dt.datetime, dt.datetime],
+ key: Callable[[dict], str] = _fingerprint_key,
) -> list[dict]:
"""Classify serialized mined patterns from a current window against a baseline window.
@@ -71,8 +109,8 @@ def diff_patterns(
# divide by zero below — treat a misconfigured env var as the default.
shift_ratio = 2.0
- current_groups = _group_by_fingerprint(current)
- baseline_groups = _group_by_fingerprint(baseline)
+ current_groups = _group_by_key(current, key)
+ baseline_groups = _group_by_key(baseline, key)
def above_floor(share: float, group: list[dict]) -> bool:
# Error severity is checked across every template in the group, not just the
@@ -147,7 +185,14 @@ def _entry(
}
-def run_patterns_diff(team: "Team", query: LogsQuery, baseline_date_range: DateRange | None) -> dict:
+def run_patterns_diff(
+ team: "Team",
+ query: LogsQuery,
+ baseline_date_range: DateRange | None,
+ *,
+ user: "User | None" = None,
+ limit: int | None = None,
+) -> dict:
"""Mine the query's window and a baseline window, and return classified diff entries.
The baseline defaults to the same window shifted back one week — log streams have strong
@@ -155,7 +200,7 @@ def run_patterns_diff(team: "Team", query: LogsQuery, baseline_date_range: DateR
preceding hour. The current window is resolved once and the baseline derived from the
resolved bounds, so a relative ``date_from`` (e.g. ``-1h``) can't drift between the two runs.
"""
- current_runner = PatternsQueryRunner(team=team, query=query)
+ current_runner = PatternsQueryRunner(team=team, query=query, user=user)
current_from = current_runner.query_date_range.date_from()
current_to = current_runner.query_date_range.date_to()
@@ -165,25 +210,151 @@ def run_patterns_diff(team: "Team", query: LogsQuery, baseline_date_range: DateR
date_to=(current_to - _BASELINE_OFFSET).isoformat(),
)
baseline_query = query.model_copy(update={"dateRange": baseline_date_range})
- baseline_runner = PatternsQueryRunner(team=team, query=baseline_query)
- current_runner.use_stored_patterns = False
- baseline_runner.use_stored_patterns = False
+ baseline_runner = PatternsQueryRunner(team=team, query=baseline_query, user=user)
baseline_from = baseline_runner.query_date_range.date_from()
baseline_to = baseline_runner.query_date_range.date_to()
- current_results = current_runner.run(ExecutionMode.CALCULATE_BLOCKING_ALWAYS).results
- baseline_results = baseline_runner.run(ExecutionMode.CALCULATE_BLOCKING_ALWAYS).results
+ versions = {runner.stored_version() for runner in (current_runner, baseline_runner)}
+ version = versions.pop() if len(versions) == 1 else None
+ if version is None:
+ current_runner.use_stored_patterns = baseline_runner.use_stored_patterns = False
+ results = [
+ runner.run(ExecutionMode.CALCULATE_BLOCKING_ALWAYS).results for runner in (current_runner, baseline_runner)
+ ]
+ current_results, baseline_results = results
entries = diff_patterns(
current_results["patterns"],
baseline_results["patterns"],
current_window=(current_from, current_to),
baseline_window=(baseline_from, baseline_to),
+ key=stored_pattern_keys(current_results["patterns"], baseline_results["patterns"])
+ if version
+ else _fingerprint_key,
)
+ truncated = limit is not None and len(entries) > limit
+ entries = entries[:limit]
+ first_seen = _first_seen_ever(team, query, entries, version, current_to) if version else {}
+ history_failed = first_seen is None
+ first_seen = first_seen or {}
+ for entry in entries:
+ pattern = entry["pattern"]
+ seen = [first_seen[member] for member in pattern.get("match_patterns") or [] if member in first_seen]
+ entry.update(
+ masked_example=pattern["pattern"],
+ services=pattern.get("services") or [],
+ first_seen_ever=utc_iso(min(seen)) if seen else None,
+ )
+
+ notes = [
+ "first_seen_ever reads the pattern rollup up to 14 days back, filtered by serviceNames and severityLevels only."
+ if version
+ else "Body mining fallback: counts are sample estimates and first_seen_ever is null."
+ ]
+ if history_failed:
+ notes.append("The first_seen_ever lookup hit its read budget, so first_seen_ever is null.")
+ if baseline_results["total_count"] == 0:
+ notes.append("The baseline window has no matching logs, so every pattern reads as new.")
+
return {
+ "window": window_echo((current_from, current_to), (baseline_from, baseline_to)),
+ "source": "stored_patterns" if version else "body_mining",
+ "pattern_version": version,
+ "sampled": not version,
+ "truncated": truncated,
"entries": entries,
"current": _window_meta(current_results, current_from, current_to),
"baseline": _window_meta(baseline_results, baseline_from, baseline_to),
+ "notes": notes,
+ "next": [
+ call
+ for entry in entries
+ if entry["classification"] in ("new", "rate_shift")
+ and (call := _raw_lines_call(entry, query, current_from, current_to)) is not None
+ ][:3],
+ }
+
+
+def _first_seen_ever(
+ team: "Team", query: LogsQuery, entries: list[dict], version: int, current_to: dt.datetime
+) -> dict[str, dt.datetime] | None:
+ members = list(dict.fromkeys(member for entry in entries for member in entry["pattern"]["match_patterns"]))
+ members = members[:_FIRST_SEEN_MAX_MEMBERS] or [""]
+ where = "pattern_version = {version} AND pattern IN {members} AND time_bucket >= {date_from} AND time_bucket < {date_to}"
+ if query.serviceNames:
+ where += " AND service_name IN {services}"
+ if query.severityLevels:
+ where += " AND severity_text IN {severities}"
+ placeholders: dict[str, ast.Expr] = {
+ "version": ast.Constant(value=version),
+ "members": ast.Constant(value=members),
+ "date_from": ast.Constant(value=current_to - FIRST_SEEN_LOOKBACK),
+ "date_to": ast.Constant(value=current_to),
+ "services": ast.Constant(value=list(query.serviceNames or [])),
+ "severities": ast.Constant(value=[str(level) for level in query.severityLevels or []]),
+ }
+ select = parse_select(
+ "SELECT pattern, min(time_bucket) FROM posthog.logs_pattern_buckets WHERE {where} GROUP BY pattern LIMIT {limit}",
+ placeholders={"where": parse_expr(where, placeholders=placeholders), "limit": ast.Constant(value=len(members))},
+ )
+ try:
+ response = execute_hogql_query(
+ query_type="LogsPatternsFirstSeen",
+ query=select,
+ team=team,
+ workload=Workload.LOGS,
+ settings=fail_fast_aggregate_settings(),
+ )
+ except (CHQueryErrorTooManyBytes, ClickHouseQueryTimeOut):
+ return None
+ return {row[0]: row[1] for row in response.results}
+
+
+def _raw_lines_call(entry: dict, query: LogsQuery, date_from: dt.datetime, date_to: dt.datetime) -> dict | None:
+ pattern = entry["pattern"]
+ regex = pattern.get("match_regex")
+ if not pattern.get("pattern_version") and not regex and not pattern.get("match_literal"):
+ return None
+ scope = [
+ prop.model_dump(exclude_none=True)
+ for group in (query.filterGroup.values if query.filterGroup else [])
+ for prop in getattr(group, "values", [])
+ ]
+ pivot = (
+ [
+ {"key": "pattern", "value": pattern["match_patterns"], "operator": "exact", "type": "log"},
+ {"key": "pattern_version", "value": pattern["pattern_version"], "operator": "exact", "type": "log"},
+ ]
+ if pattern.get("pattern_version")
+ else [
+ {
+ "key": "message",
+ "value": regex or pattern["match_literal"],
+ "operator": "regex" if regex else "icontains",
+ "type": "log",
+ }
+ ]
+ )
+ scoped = {
+ name: value
+ for name, value in (
+ ("severityLevels", [str(level) for level in query.severityLevels or []]),
+ ("searchTerm", query.searchTerm),
+ ("personId", query.personId),
+ ("sessionId", query.sessionId),
+ )
+ if value
+ }
+ return {
+ "tool": "query-logs",
+ "why": f"raw lines for {entry['classification']} pattern {entry['masked_example'][:60]}",
+ "query": {
+ "dateRange": {"date_from": utc_iso(date_from), "date_to": utc_iso(date_to)},
+ "serviceNames": entry["services"] or list(query.serviceNames or []),
+ **scoped,
+ "filterGroup": scope + pivot,
+ "limit": 20,
+ },
}
diff --git a/products/logs/backend/patterns_query_runner.py b/products/logs/backend/patterns_query_runner.py
index a5634102d804..298bde559d2a 100644
--- a/products/logs/backend/patterns_query_runner.py
+++ b/products/logs/backend/patterns_query_runner.py
@@ -15,6 +15,8 @@ from posthog.hogql.parser import parse_expr, parse_select
from posthog.hogql.query import execute_hogql_query
from posthog.clickhouse.client.connection import Workload
+from posthog.clickhouse.client.limit import app_org_concurrency_slot
+from posthog.dataclasses import frozen
from posthog.exceptions import ClickHouseQueryTimeOut
from posthog.hogql_queries.query_runner import AnalyticsQueryRunner
from posthog.utils import get_instance_region
@@ -37,6 +39,13 @@ _TimeSlice = tuple[dt.datetime, dt.datetime]
STORED_PATTERN_HEAD_MAX_BYTES = 65536
+@frozen
+class _VersionCoverage:
+ total: int
+ covered: int
+ version: int
+
+
class PatternsQueryRunner(AnalyticsQueryRunner[LogsQueryResponse], LogsQueryRunnerMixin):
"""Mines log templates (Drain3) from a bounded, deterministic sample of the matching logs.
@@ -116,23 +125,41 @@ class PatternsQueryRunner(AnalyticsQueryRunner[LogsQueryResponse], LogsQueryRunn
def _calculate(self) -> LogsQueryResponse:
reason = "comparison" if not self.use_stored_patterns else "flag_disabled"
if self.use_stored_patterns and self._stored_patterns_enabled:
- self._query_deadline = monotonic() + max(1, self.settings.max_execution_time or 60)
- versions = self._execute(
- parse_select(
- "SELECT pattern_version, count(), countIf(trim(pattern) != '') FROM logs WHERE {where} GROUP BY pattern_version",
- placeholders={"where": self._where_with_timestamp()},
- )
- ).results
- total = sum(int(row[1]) for row in versions)
- candidates = [(int(row[2]), int(row[0])) for row in versions if int(row[0]) > 0]
- covered, version = max(candidates, default=(0, 0))
+ self._start_deadline()
+ coverage = self._version_coverage
+ total, covered, version = coverage.total, coverage.covered, coverage.version
if total and covered * 100 >= total * 99:
return self._calculate_stored_patterns(total, version, covered)
reason = "insufficient_version_coverage" if total else "empty_window"
else:
- total = self._count()
+ cached = self.__dict__.get("_version_coverage")
+ total = cached.total if cached is not None else self._count()
return self._calculate_body_patterns(total, reason)
+ def _start_deadline(self) -> None:
+ if self._query_deadline is None:
+ self._query_deadline = monotonic() + max(1, self.settings.max_execution_time or 60)
+
+ @cached_property
+ def _version_coverage(self) -> "_VersionCoverage":
+ versions = self._execute(
+ parse_select(
+ "SELECT pattern_version, count(), countIf(trim(pattern) != '') FROM logs WHERE {where} GROUP BY pattern_version",
+ placeholders={"where": self._where_with_timestamp()},
+ )
+ ).results
+ candidates = [(int(row[2]), int(row[0])) for row in versions if int(row[0]) > 0]
+ covered, version = max(candidates, default=(0, 0))
+ return _VersionCoverage(total=sum(int(row[1]) for row in versions), covered=covered, version=version)
+
+ def stored_version(self) -> int | None:
+ if not (self.use_stored_patterns and self._stored_patterns_enabled):
+ return None
+ self._start_deadline()
+ with app_org_concurrency_slot(self.team, task_id=self.query_id):
+ coverage = self._version_coverage
+ return coverage.version if coverage.total and coverage.covered * 100 >= coverage.total * 99 else None
+
@cached_property
def _stored_patterns_enabled(self) -> bool:
# only_evaluate_locally keeps this check off the network: it gates an interactive query, so
diff --git a/products/logs/backend/presentation/views/agent_fields.py b/products/logs/backend/presentation/views/agent_fields.py
new file mode 100644
index 000000000000..20d0740b271c
--- /dev/null
+++ b/products/logs/backend/presentation/views/agent_fields.py
@@ -0,0 +1,23 @@
+from rest_framework import serializers
+
+
+class LogsAgentWindowBoundsSerializer(serializers.Serializer):
+ def get_fields(self) -> dict[str, serializers.Field]:
+ return {
+ "from": serializers.CharField(help_text="Window start, ISO 8601 UTC with a Z suffix (inclusive)."),
+ "to": serializers.CharField(help_text="Window end, ISO 8601 UTC with a Z suffix (exclusive)."),
+ }
+
+
+class LogsAgentWindowSerializer(serializers.Serializer):
+ current = LogsAgentWindowBoundsSerializer(help_text="Absolute bounds the server used for the current window.")
+ baseline = LogsAgentWindowBoundsSerializer(
+ required=False, help_text="Absolute bounds the server used for the baseline window, when there is one."
+ )
+ timezone = serializers.CharField(help_text='Always "UTC".')
+
+
+class LogsAgentNextCallSerializer(serializers.Serializer):
+ tool = serializers.CharField(help_text="MCP tool to call next, e.g. query-logs or logs-context.")
+ why = serializers.CharField(help_text="One line on what the follow-up call answers.")
+ query = serializers.DictField(help_text="Prefilled `query` object for that tool. Pass it as is or adjust it.")
diff --git a/products/logs/backend/presentation/views/api.py b/products/logs/backend/presentation/views/api.py
index 7e894f31ee6b..89ec84ac9c59 100644
--- a/products/logs/backend/presentation/views/api.py
+++ b/products/logs/backend/presentation/views/api.py
@@ -74,6 +74,11 @@ 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
@@ -1191,8 +1196,12 @@ class _LogsPatternsResponseSerializer(_LogsPatternsSourceSerializer):
)
+class _LogsPatternsDiffBodySerializer(_LogsPatternsBodySerializer, PatternsDiffBodyFields):
+ pass
+
+
class _LogsPatternsDiffRequestSerializer(serializers.Serializer):
- query = _LogsPatternsBodySerializer(
+ 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."
@@ -1208,7 +1217,7 @@ class _LogsPatternsDiffRequestSerializer(serializers.Serializer):
)
-class _LogPatternDiffEntrySerializer(serializers.Serializer):
+class _LogPatternDiffEntrySerializer(PatternDiffEntryFields):
classification = serializers.ChoiceField(
choices=["new", "rate_shift", "gone", "unchanged"],
help_text=(
@@ -1262,7 +1271,7 @@ class _LogsPatternsDiffWindowSerializer(_LogsPatternsSourceSerializer):
date_to = serializers.CharField(help_text="Resolved window end (ISO 8601, exclusive).")
-class _LogsPatternsDiffResponseSerializer(serializers.Serializer):
+class _LogsPatternsDiffResponseSerializer(PatternsDiffResponseFields):
entries = _LogPatternDiffEntrySerializer(
many=True,
help_text=(
@@ -1970,7 +1979,15 @@ class LogsViewSet(TeamAndOrgViewSetMixin, PydanticModelMixin, viewsets.ViewSet):
else None
)
- results = run_patterns_diff(self.team, query, baseline_date_range)
+ 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"),
+ )
report_user_action(
request.user,
diff --git a/products/logs/backend/presentation/views/patterns_diff_fields.py b/products/logs/backend/presentation/views/patterns_diff_fields.py
new file mode 100644
index 000000000000..6322cfe8e8c7
--- /dev/null
+++ b/products/logs/backend/presentation/views/patterns_diff_fields.py
@@ -0,0 +1,44 @@
+from django.db import models
+
+from rest_framework import serializers
+
+from products.logs.backend.presentation.views.agent_fields import LogsAgentNextCallSerializer, LogsAgentWindowSerializer
+
+
+class PatternsDiffSource(models.TextChoices):
+ STORED_PATTERNS = "stored_patterns"
+ BODY_MINING = "body_mining"
+
+
+class PatternsDiffBodyFields(serializers.Serializer):
+ limit = serializers.IntegerField(
+ required=False,
+ allow_null=True,
+ min_value=1,
+ max_value=500,
+ help_text="Return at most this many entries, most interesting first. Omit for all. Sets `truncated`.",
+ )
+
+
+class PatternDiffEntryFields(serializers.Serializer):
+ masked_example = serializers.CharField(help_text="The template with variable parts masked.")
+ services = serializers.ListField(child=serializers.CharField(), help_text="Up to 4 services with this pattern.")
+ first_seen_ever = serializers.CharField(
+ allow_null=True,
+ help_text="Earliest 5-minute bucket (UTC) with this pattern, up to 14 days back. Null on body mining.",
+ )
+
+
+class PatternsDiffResponseFields(serializers.Serializer):
+ window = LogsAgentWindowSerializer(help_text="Absolute UTC bounds of the current and baseline windows.")
+ source = serializers.ChoiceField( # type: ignore[assignment] # field named `source` shadows DRF Field.source
+ choices=PatternsDiffSource.choices,
+ help_text="stored_patterns when both windows have ≥99% of rows on the same stored version, else body_mining.",
+ )
+ pattern_version = serializers.IntegerField(allow_null=True, help_text="Stored pattern version, null for mining.")
+ sampled = serializers.BooleanField(help_text="True on the body-mining fallback: counts are sample estimates.")
+ truncated = serializers.BooleanField(help_text="True when `limit` cut the entry list.")
+ notes = serializers.ListField(child=serializers.CharField(), help_text="Caveats that limit what the diff shows.")
+ next = LogsAgentNextCallSerializer(
+ many=True, help_text="Prefilled query-logs calls for the top new or shifted patterns."
+ )
diff --git a/products/logs/backend/test/test_pattern_diff.py b/products/logs/backend/test/test_pattern_diff.py
index 30c7e4eb9c9d..073d018ce1ef 100644
--- a/products/logs/backend/test/test_pattern_diff.py
+++ b/products/logs/backend/test/test_pattern_diff.py
@@ -1,18 +1,37 @@
import json
import datetime as dt
+from typing import Any
import time_machine
from posthog.test.base import APIBaseTest, ClickhouseTestMixin
from unittest import TestCase
+from unittest.mock import MagicMock, patch
from parameterized import parameterized
-from posthog.schema import DateRange, FilterLogicalOperator, LogsQuery, PropertyGroupFilter
+from posthog.schema import (
+ DateRange,
+ FilterLogicalOperator,
+ LogPropertyFilter,
+ LogsQuery,
+ PropertyGroupFilter,
+ PropertyGroupFilterValue,
+ PropertyOperator,
+)
from posthog.clickhouse.client import sync_execute
+from posthog.errors import CHQueryErrorTooManyBytes
+from posthog.exceptions import ClickHouseQueryTimeOut
from products.logs.backend.log_patterns import pattern_fingerprint
-from products.logs.backend.pattern_diff import diff_patterns, run_patterns_diff
+from products.logs.backend.pattern_diff import (
+ _first_seen_ever,
+ _raw_lines_call,
+ diff_patterns,
+ run_patterns_diff,
+ stored_pattern_keys,
+)
+from products.logs.backend.patterns_query_runner import PatternsQueryRunner
_HOUR = (dt.datetime(2026, 6, 23, 12, 0), dt.datetime(2026, 6, 23, 13, 0))
_BASELINE_HOUR = (dt.datetime(2026, 6, 16, 12, 0), dt.datetime(2026, 6, 16, 13, 0))
@@ -229,3 +248,322 @@ class TestRunPatternsDiff(ClickhouseTestMixin, APIBaseTest):
assert results["baseline"]["date_from"].startswith("2026-06-20T12:00:00")
assert results["baseline"]["total_count"] == 2
+
+
+class TestStoredPatternKeys(TestCase):
+ def test_groups_sharing_a_stored_member_compare_as_one_pattern(self) -> None:
+ current = [
+ {
+ **_pattern("Retry <*> timed out", count=100),
+ "match_patterns": ["Retry <N> timed out", "Retry <N> timed out again"],
+ }
+ ]
+ baseline = [{**_pattern("Retry <N> timed out", count=50), "match_patterns": ["Retry <N> timed out"]}]
+
+ keys = stored_pattern_keys(current, baseline)
+ entries = diff_patterns(current, baseline, current_window=_HOUR, baseline_window=_BASELINE_HOUR, key=keys)
+
+ assert [e["classification"] for e in entries] == ["rate_shift"]
+
+ def test_a_baseline_group_spanning_two_current_groups_matches_both(self) -> None:
+ current = [
+ {**_pattern("Retry <*> timed out", count=100), "match_patterns": ["Retry <N> timed out"]},
+ {**_pattern("Retry <*> timed out again", count=100), "match_patterns": ["Retry <N> timed out again"]},
+ ]
+ baseline = [
+ {
+ **_pattern("Retry <*> timed out", count=100),
+ "match_patterns": ["Retry <N> timed out again", "Retry <N> timed out"],
+ }
+ ]
+
+ keys = stored_pattern_keys(current, baseline)
+ entries = diff_patterns(current, baseline, current_window=_HOUR, baseline_window=_BASELINE_HOUR, key=keys)
+
+ assert "new" not in [e["classification"] for e in entries]
+
+
+def _bare_query() -> LogsQuery:
+ return LogsQuery(
+ dateRange=DateRange(date_from="-1h"),
+ filterGroup=PropertyGroupFilter(type=FilterLogicalOperator.AND_, values=[]),
+ severityLevels=[],
+ serviceNames=[],
+ )
+
+
+class TestRawLinesCall(TestCase):
+ _WINDOW = (dt.datetime(2026, 6, 23, 12, 0, tzinfo=dt.UTC), dt.datetime(2026, 6, 23, 13, 0, tzinfo=dt.UTC))
+
+ def _entry(self, **pattern: Any) -> dict:
+ return {"classification": "new", "masked_example": "boom <*>", "services": ["api"], "pattern": pattern}
+
+ def test_keeps_the_original_scope_and_adds_the_pattern(self) -> None:
+ query = LogsQuery(
+ dateRange=DateRange(date_from="-1h"),
+ serviceNames=[],
+ severityLevels=["error"],
+ searchTerm="checkout",
+ filterGroup=PropertyGroupFilter(
+ type=FilterLogicalOperator.AND_,
+ values=[
+ PropertyGroupFilterValue(
+ type=FilterLogicalOperator.AND_,
+ values=[
+ LogPropertyFilter(key="env", value="prod", operator=PropertyOperator.EXACT, type="log")
+ ],
+ )
+ ],
+ ),
+ )
+
+ call = _raw_lines_call(self._entry(match_regex="boom .*"), query, *self._WINDOW)
+
+ assert call is not None
+ assert call["query"]["severityLevels"] == ["error"]
+ assert call["query"]["searchTerm"] == "checkout"
+ assert [f["key"] for f in call["query"]["filterGroup"]] == ["env", "message"]
+
+ def test_omits_the_call_without_a_matcher(self) -> None:
+ query = _bare_query()
+
+ assert _raw_lines_call(self._entry(match_regex=None, match_literal=""), query, *self._WINDOW) is None
+
+
+class TestFirstSeenEver(TestCase):
+ _ENTRIES = [{"pattern": {"match_patterns": [f"pattern {i}" for i in range(150)]}}]
+
+ def test_sets_an_explicit_limit_for_every_member(self) -> None:
+ with patch("products.logs.backend.pattern_diff.execute_hogql_query") as execute:
+ execute.return_value.results = []
+ _first_seen_ever(MagicMock(), _bare_query(), self._ENTRIES, 1, dt.datetime.now(dt.UTC))
+
+ assert execute.call_args.kwargs["query"].limit.value == 150
+
+ def test_returns_none_when_the_history_lookup_hits_its_budget(self) -> None:
+ with patch(
+ "products.logs.backend.pattern_diff.execute_hogql_query", side_effect=CHQueryErrorTooManyBytes("too many")
+ ):
+ result = _first_seen_ever(MagicMock(), _bare_query(), self._ENTRIES, 1, dt.datetime.now(dt.UTC))
+
+ assert result is None
+
+
+class TestRunPatternsDiffV2(ClickhouseTestMixin, APIBaseTest):
+ CLASS_DATA_LEVEL_SETUP = False
+
+ def _insert(self, rows: list[dict]) -> None:
+ sql = "".join(json.dumps({"team_id": self.team.id, **r}) + "\n" for r in rows)
+ sync_execute(f"INSERT INTO logs FORMAT JSONEachRow\n{sql}")
+
+ def _log(
+ self,
+ body: str,
+ *,
+ day: int,
+ severity: str = "info",
+ service: str = "api",
+ minute: int = 0,
+ stored: str | None = None,
+ ) -> dict:
+ row: dict[str, str | int] = {
+ "timestamp": f"2026-06-{day:02d} 12:{minute:02d}:00.000000",
+ "body": body,
+ "severity_text": severity,
+ "service_name": service,
+ }
+ if stored is not None:
+ row.update({"pattern": stored, "pattern_version": 5})
+ return row
+
+ def _query(self, severity_levels: list[str] | None = None) -> LogsQuery:
+ return LogsQuery(
+ dateRange=DateRange(date_from="2026-06-23T12:00:00Z", date_to="2026-06-23T13:00:00Z"),
+ filterGroup=PropertyGroupFilter(type=FilterLogicalOperator.AND_, values=[]),
+ severityLevels=severity_levels or [],
+ serviceNames=[],
+ searchTerm=None,
+ )
+
+ def _seed_stored(self, *, stamp_baseline: bool = True) -> None:
+ retry = [
+ self._log(
+ f"Retry {i} timed out",
+ day=23,
+ severity="error",
+ service="worker",
+ minute=i,
+ stored="Retry <N> timed out",
+ )
+ for i in range(3)
+ ]
+ archive_current = [
+ self._log(f"Archive job run_{i} queued", day=23, minute=i, stored="Archive job <ID> queued")
+ for i in range(3)
+ ]
+ archive_baseline = [
+ self._log(
+ f"Archive job run_{i} queued",
+ day=16,
+ minute=i,
+ stored="Archive job <ID> queued" if stamp_baseline else None,
+ )
+ for i in range(3)
+ ]
+ archive_history = [self._log("Archive job run_old queued", day=12, stored="Archive job <ID> queued")]
+ rows = retry + archive_current + archive_baseline + archive_history
+ self._insert(rows)
+ # The test `logs` table feeds no pattern rollup, so write the rows its materialized view would.
+ rollup = "".join(
+ json.dumps(
+ {
+ "team_id": self.team.id,
+ "time_bucket": row["timestamp"][:15] + "0:00",
+ "service_name": row["service_name"],
+ "severity_text": row["severity_text"],
+ "pattern_version": 5,
+ "pattern": row["pattern"],
+ "log_count": 1,
+ }
+ )
+ + "\n"
+ for row in rows
+ if "pattern" in row
+ )
+ sync_execute(f"INSERT INTO logs_pattern_buckets FORMAT JSONEachRow\n{rollup}")
+
+ @time_machine.travel(_FROZEN_NOW, tick=False)
+ def test_stored_patterns_are_used_when_both_windows_are_covered(self) -> None:
+ self._seed_stored()
+
+ with patch("posthoganalytics.feature_enabled", return_value=True):
+ results = run_patterns_diff(self.team, self._query(), None)
+
+ assert results["source"] == "stored_patterns"
+ assert results["pattern_version"] == 5
+ assert results["sampled"] is False
+ assert results["current"]["source"] == results["baseline"]["source"] == "stored_patterns"
+ by_example = {e["masked_example"]: e for e in results["entries"]}
+ retry = by_example["Retry <N> timed out"]
+ assert retry["classification"] == "new"
+ assert retry["services"] == ["worker"]
+ assert retry["first_seen_ever"] == "2026-06-23T12:00:00Z"
+ archive = by_example["Archive job <ID> queued"]
+ assert archive["classification"] == "unchanged"
+ assert archive["first_seen_ever"] == "2026-06-12T12:00:00Z"
+
+ @time_machine.travel(_FROZEN_NOW, tick=False)
+ def test_the_version_check_shares_the_runner_time_budget(self) -> None:
+ self._seed_stored(stamp_baseline=False)
+ clock = iter([0.0, 0.0] + [1000.0] * 100)
+
+ with (
+ patch("posthoganalytics.feature_enabled", return_value=True),
+ patch("products.logs.backend.patterns_query_runner.monotonic", side_effect=lambda: next(clock)),
+ self.assertRaises(ClickHouseQueryTimeOut),
+ ):
+ run_patterns_diff(self.team, self._query(), None)
+
+ @time_machine.travel(_FROZEN_NOW, tick=False)
+ def test_partial_coverage_falls_back_to_body_mining_in_both_windows(self) -> None:
+ self._seed_stored(stamp_baseline=False)
+
+ with (
+ patch("posthoganalytics.feature_enabled", return_value=True),
+ patch.object(PatternsQueryRunner, "_calculate_stored_patterns", side_effect=AssertionError),
+ patch.object(PatternsQueryRunner, "_count", side_effect=AssertionError),
+ patch("products.logs.backend.patterns_query_runner.app_org_concurrency_slot") as slot,
+ ):
+ results = run_patterns_diff(self.team, self._query(), None)
+
+ assert slot.call_count == 2
+
+ assert results["source"] == "body_mining"
+ assert results["sampled"] is True
+ assert results["current"]["source"] == results["baseline"]["source"] == "body_mining"
+ assert sorted(e["classification"] for e in results["entries"]) == ["new", "unchanged"]
+ assert all(e["first_seen_ever"] is None for e in results["entries"])
+ assert any("first_seen_ever" in note for note in results["notes"])
+
+ @time_machine.travel(_FROZEN_NOW, tick=False)
+ def test_body_mining_entries_carry_masked_examples_and_pivots(self) -> None:
+ self._insert(
+ [self._log(f"User {name} not found", day=23, severity="error") for name in ("alice", "bob", "carol")]
+ )
+
+ plain = run_patterns_diff(self.team, self._query(), None)
+
+ entry = plain["entries"][0]
+ assert entry["masked_example"] == "User <*> not found"
+ assert entry["services"] == ["api"]
+ assert plain["window"] == {
+ "current": {"from": "2026-06-23T12:00:00Z", "to": "2026-06-23T13:00:00Z"},
+ "baseline": {"from": "2026-06-16T12:00:00Z", "to": "2026-06-16T13:00:00Z"},
+ "timezone": "UTC",
+ }
+ assert plain["next"][0]["tool"] == "query-logs"
+ assert plain["next"][0]["query"]["filterGroup"][0]["operator"] == "regex"
+
+ @time_machine.travel(_FROZEN_NOW, tick=False)
+ def test_severity_levels_scope_both_windows(self) -> None:
+ self._insert(
+ [
+ self._log("disk almost full", day=23, severity="warn"),
+ self._log("heartbeat ok", day=23),
+ self._log("heartbeat ok", day=16),
+ ]
+ )
+
+ results = run_patterns_diff(self.team, self._query(["warn", "error", "fatal"]), None)
+
+ assert [e["masked_example"] for e in results["entries"]] == ["disk almost full"]
+ assert results["baseline"]["total_count"] == 0
+
+ @time_machine.travel(_FROZEN_NOW, tick=False)
+ def test_limit_truncates_entries(self) -> None:
+ self._insert([self._log("first new thing", day=23), self._log("second new thing", day=23)])
+
+ results = run_patterns_diff(self.team, self._query(), None, limit=1)
+
+ assert len(results["entries"]) == 1
+ assert results["truncated"] is True
+
+
+class TestPatternsDiffAPIV2(ClickhouseTestMixin, APIBaseTest):
+ CLASS_DATA_LEVEL_SETUP = False
+
+ @time_machine.travel(_FROZEN_NOW, tick=False)
+ def test_endpoint_accepts_limit(self) -> None:
+ sql = "".join(
+ json.dumps(
+ {
+ "team_id": self.team.id,
+ "timestamp": f"2026-06-23 12:0{i}:00.000000",
+ "body": body,
+ "severity_text": "error",
+ "service_name": "api",
+ }
+ )
+ + "\n"
+ for i, body in enumerate(["socket closed by peer", "queue overflow detected"])
+ )
+ sync_execute(f"INSERT INTO logs FORMAT JSONEachRow\n{sql}")
+
+ response = self.client.post(
+ f"/api/projects/{self.team.id}/logs/patterns_diff/",
+ {
+ "query": {
+ "dateRange": {"date_from": "2026-06-23T12:00:00Z", "date_to": "2026-06-23T13:00:00Z"},
+ "severityLevels": ["error"],
+ "limit": 1,
+ }
+ },
+ format="json",
+ )
+
+ assert response.status_code == 200, response.content
+ body = response.json()
+ assert len(body["entries"]) == 1
+ assert body["truncated"] is True
+ assert body["sampled"] is True
+ assert body["window"]["timezone"] == "UTC"
diff --git a/products/logs/evals/eval_agent_observability.py b/products/logs/evals/eval_agent_observability.py
new file mode 100644
index 000000000000..d5e258636f4f
--- /dev/null
+++ b/products/logs/evals/eval_agent_observability.py
@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from posthog.clickhouse.client import sync_execute
+
+from products.posthog_ai.eval_harness.base import SandboxedPublicEval
+from products.posthog_ai.eval_harness.config import SandboxedEvalCase
+from products.posthog_ai.eval_harness.harness.context import EvalContext
+from products.posthog_ai.eval_harness.log_parser import LogParser
+from products.posthog_ai.eval_harness.scorers.contract import Score, Scorer
+from products.tasks.backend.facade.agents import CustomPromptSandboxContext
+
+RUN_ID = "run-7f3a9c"
+NEW_ERROR = "card vault handshake timed out"
+SILENT = "ledger-sync"
+
+
+def seed_observability_logs(context: CustomPromptSandboxContext) -> dict[str, Any]:
+ now = datetime.now(UTC).replace(second=0, microsecond=0)
+ spike_start = now - timedelta(minutes=40)
+
+ def log(at: datetime, service: str, body: str, severity: str = "info", **attributes: str) -> dict:
+ stamp = at.strftime("%Y-%m-%d %H:%M:%S.%f")
+ return {
+ "team_id": context.team_id,
+ "uuid": str(uuid.uuid4()),
+ "timestamp": stamp,
+ "observed_timestamp": stamp,
+ "body": body,
+ "severity_text": severity,
+ "service_name": service,
+ "attributes_map_str": {f"{key}__str": value for key, value in attributes.items()},
+ }
+
+ rows = [log(now - timedelta(minutes=m), "checkout", f"order {m} placed") for m in range(0, 24 * 60, 10)]
+ rows += [log(now - timedelta(days=1, minutes=m), SILENT, "ledger batch synced") for m in range(0, 600, 10)]
+ rows += [log(spike_start + timedelta(seconds=s), "checkout", NEW_ERROR, "error") for s in range(0, 2400, 5)]
+ rows += [
+ log(now - timedelta(hours=2, seconds=s), service, body, severity, workflow_run_id=RUN_ID)
+ for s, service, body, severity in (
+ (60, "scheduler", "run queued", "info"),
+ (50, "worker", "step upload started", "info"),
+ (20, "worker", "step upload failed: quota exceeded", "error"),
+ )
+ ]
+ sync_execute("INSERT INTO logs FORMAT JSONEachRow\n" + "".join(json.dumps(row) + "\n" for row in rows))
+ return {"spike_hhmm": spike_start.strftime("%H:%M")}
+
+
+class AnswerMentions(Scorer):
+ def _name(self) -> str:
+ return "answer_mentions"
+
+ def _run_eval_sync(self, output: dict | None, expected: dict | None = None, **kwargs: Any) -> Score:
+ parser = LogParser.cached(output["raw_log"]) if output and output.get("raw_log") else None
+ message = ((parser.get_final_agent_message() if parser else None) or "").lower()
+ seed = (output or {}).get("seed") or {}
+ expected_terms = (expected or {}).get(self._name()) or []
+ terms = [str(seed.get(term[5:], term)) if term.startswith("seed:") else term for term in expected_terms]
+ found = [term for term in terms if term.lower() in message]
+ return Score(name=self._name(), score=len(found) / len(terms) if terms else None, metadata={"found": found})
+
+
+class CallBudget(Scorer):
+ def _name(self) -> str:
+ return "call_budget"
+
+ def _run_eval_sync(self, output: dict | None, expected: dict | None = None, **kwargs: Any) -> Score:
+ budget = (expected or {}).get(self._name())
+ if not budget or not output or not output.get("raw_log"):
+ return Score(name=self._name(), score=None if not budget else 0.0)
+ calls = sum(1 for call in LogParser.cached(output["raw_log"]).get_tool_calls() if not call.is_error)
+ return Score(name=self._name(), score=min(1.0, budget / max(calls, 1)), metadata={"calls": calls})
+
+
+CASES = [
+ ("daily_health", "Write a health report of my services for the last 24h of logs.", ["checkout", SILENT], 4),
+ ("silent_service", "Did a service stop sending logs in the last 24h, compared with the day before?", [SILENT], 2),
+ ("new_error_pattern", "Which error messages are new in the logs in the last 24h?", [NEW_ERROR, "checkout"], 2),
+ ("logs_for_one_run", f"Workflow run {RUN_ID} failed about 2h ago. What happened?", ["quota exceeded", "worker"], 3),
+ ("spike_onset", "Checkout errors spiked in the last 2h. When did the spike start, in UTC?", ["seed:spike_hhmm"], 3),
+]
+
+
+async def eval_agent_observability(ctx: EvalContext) -> None:
+ await SandboxedPublicEval(
+ experiment_name="sandboxed-logs-agent-observability-cli",
+ cases=[
+ SandboxedEvalCase(
+ name=name,
+ prompt=prompt,
+ expected={"answer_mentions": terms, "call_budget": budget},
+ setup=seed_observability_logs,
+ )
+ for name, prompt, terms, budget in CASES
+ ],
+ scorers=[AnswerMentions(), CallBudget()],
+ ctx=ctx,
+ )
diff --git a/products/logs/frontend/components/LogsPatterns/logsPatternsLogic.test.ts b/products/logs/frontend/components/LogsPatterns/logsPatternsLogic.test.ts
index 16c929658fbc..89e7b798d61a 100644
--- a/products/logs/frontend/components/LogsPatterns/logsPatternsLogic.test.ts
+++ b/products/logs/frontend/components/LogsPatterns/logsPatternsLogic.test.ts
@@ -69,6 +69,9 @@ const DIFF_RESPONSE: _LogsPatternsDiffResponseApi = {
pattern: RESPONSE.patterns[0],
baseline_estimated_count: null,
baseline_volume_share_pct: null,
+ masked_example: 'GET <*> returned <N>',
+ services: [],
+ first_seen_ever: null,
},
],
current: {
@@ -87,6 +90,17 @@ const DIFF_RESPONSE: _LogsPatternsDiffResponseApi = {
date_from: '2026-06-16T12:00:00+00:00',
date_to: '2026-06-16T13:00:00+00:00',
},
+ window: {
+ current: { from: '2026-06-23T12:00:00Z', to: '2026-06-23T13:00:00Z' },
+ baseline: { from: '2026-06-16T12:00:00Z', to: '2026-06-16T13:00:00Z' },
+ timezone: 'UTC',
+ },
+ source: 'body_mining',
+ pattern_version: null,
+ sampled: false,
+ truncated: false,
+ notes: [],
+ next: [],
}
describe('logsPatternsLogic', () => {
diff --git a/products/logs/frontend/generated/api.schemas.ts b/products/logs/frontend/generated/api.schemas.ts
index 54b5c5c728ae..1e14b563b745 100644
--- a/products/logs/frontend/generated/api.schemas.ts
+++ b/products/logs/frontend/generated/api.schemas.ts
@@ -2305,13 +2305,78 @@ export interface _LogsPatternsResponseApi {
sparkline_buckets: _LogsPatternsSparklineBucketApi[]
}
+export interface _LogsPatternsDiffBodyApi {
+ /** Date range to mine patterns from. Defaults to last hour. */
+ dateRange?: _DateRangeApi
+ /** Filter by log severity levels before mining. */
+ severityLevels?: SeverityLevelsEnumApi[]
+ /** Restrict mining to these service names. */
+ serviceNames?: string[]
+ /** Full-text search term to filter log bodies before mining. */
+ searchTerm?: string
+ /** Property filters applied before mining. Same shape as the query-logs endpoint. */
+ filterGroup?: _LogPropertyFilterApi[]
+ /** Scope mining 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. */
+ personId?: string
+ /** Scope mining 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. */
+ sessionId?: string
+ /**
+ * Return at most this many entries, most interesting first. Omit for all. Sets `truncated`.
+ * @minimum 1
+ * @maximum 500
+ * @nullable
+ */
+ limit?: number | null
+}
+
export interface _LogsPatternsDiffRequestApi {
/** 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. */
- query: _LogsPatternsBodyApi
+ query: _LogsPatternsDiffBodyApi
/** 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. */
baselineDateRange?: _DateRangeApi
}
+export interface LogsAgentWindowBoundsApi {
+ /** Window start, ISO 8601 UTC with a Z suffix (inclusive). */
+ from: string
+ /** Window end, ISO 8601 UTC with a Z suffix (exclusive). */
+ to: string
+}
+
+export interface LogsAgentWindowApi {
+ /** Absolute bounds the server used for the current window. */
+ current: LogsAgentWindowBoundsApi
+ /** Absolute bounds the server used for the baseline window, when there is one. */
+ baseline?: LogsAgentWindowBoundsApi
+ /** Always "UTC". */
+ timezone: string
+}
+
+/**
+ * * `stored_patterns` - Stored Patterns
+ * * `body_mining` - Body Mining
+ */
+export type PatternsDiffSourceEnumApi = (typeof PatternsDiffSourceEnumApi)[keyof typeof PatternsDiffSourceEnumApi]
+
+export const PatternsDiffSourceEnumApi = {
+ StoredPatterns: 'stored_patterns',
+ BodyMining: 'body_mining',
+} as const
+
+/**
+ * Prefilled `query` object for that tool. Pass it as is or adjust it.
+ */
+export type LogsAgentNextCallApiQuery = { [key: string]: unknown }
+
+export interface LogsAgentNextCallApi {
+ /** MCP tool to call next, e.g. query-logs or logs-context. */
+ tool: string
+ /** One line on what the follow-up call answers. */
+ why: string
+ /** Prefilled `query` object for that tool. Pass it as is or adjust it. */
+ query: LogsAgentNextCallApiQuery
+}
+
/**
* * `new` - new
* * `rate_shift` - rate_shift
@@ -2329,6 +2394,15 @@ export const _LogPatternDiffEntryClassificationEnumApi = {
} as const
export interface _LogPatternDiffEntryApi {
+ /** The template with variable parts masked. */
+ masked_example: string
+ /** Up to 4 services with this pattern. */
+ services: string[]
+ /**
+ * Earliest 5-minute bucket (UTC) with this pattern, up to 14 days back. Null on body mining.
+ * @nullable
+ */
+ first_seen_ever: string | null
/** "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.
*
* * `new` - new
@@ -2403,6 +2477,26 @@ export interface _LogsPatternsDiffWindowApi {
}
export interface _LogsPatternsDiffResponseApi {
+ /** Absolute UTC bounds of the current and baseline windows. */
+ window: LogsAgentWindowApi
+ /** stored_patterns when both windows have ≥99% of rows on the same stored version, else body_mining.
+ *
+ * * `stored_patterns` - Stored Patterns
+ * * `body_mining` - Body Mining */
+ source: PatternsDiffSourceEnumApi
+ /**
+ * Stored pattern version, null for mining.
+ * @nullable
+ */
+ pattern_version: number | null
+ /** True on the body-mining fallback: counts are sample estimates. */
+ sampled: boolean
+ /** True when `limit` cut the entry list. */
+ truncated: boolean
+ /** Caveats that limit what the diff shows. */
+ notes: string[]
+ /** Prefilled query-logs calls for the top new or shifted patterns. */
+ next: LogsAgentNextCallApi[]
/** 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. */
entries: _LogPatternDiffEntryApi[]
/** Mining metadata for the current window. */
diff --git a/products/logs/frontend/generated/api.zod.ts b/products/logs/frontend/generated/api.zod.ts
index 013eeec07b62..e45a4a35e690 100644
--- a/products/logs/frontend/generated/api.zod.ts
+++ b/products/logs/frontend/generated/api.zod.ts
@@ -1481,6 +1481,8 @@ export const LogsPatternsCreateBody = /* @__PURE__ */ zod.object({
.describe('The patterns query to execute.'),
})
+export const logsPatternsDiffCreateBodyQueryOneLimitMax = 500
+
export const LogsPatternsDiffCreateBody = /* @__PURE__ */ zod.object({
query: zod
.object({
@@ -1575,6 +1577,12 @@ export const LogsPatternsDiffCreateBody = /* @__PURE__ */ zod.object({
.describe(
"Scope mining 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."
),
+ limit: zod
+ .number()
+ .min(1)
+ .max(logsPatternsDiffCreateBodyQueryOneLimitMax)
+ .nullish()
+ .describe('Return at most this many entries, most interesting first. Omit for all. Sets `truncated`.'),
})
.describe(
'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.'
diff --git a/products/logs/mcp/prompts/logs-patterns-diff.md b/products/logs/mcp/prompts/logs-patterns-diff.md
index 68b0ad326933..098569dfa720 100644
--- a/products/logs/mcp/prompts/logs-patterns-diff.md
+++ b/products/logs/mcp/prompts/logs-patterns-diff.md
@@ -1,81 +1,24 @@
-Compare the log patterns of two time windows and return what changed: templates that are **new**, templates whose rate **shifted** (with magnitude, e.g. 4x), and templates that are **gone**. This is the single most useful call for incident triage — "what is different about now vs. before it broke" in one round trip, instead of mining two windows yourself and hand-matching templates.
+Compare the log patterns of a current window with a baseline window. Use it for "which error patterns are new or worse?" in one call. Do not mine two windows and match templates yourself.
-All parameters go inside `query`, except the optional sibling `baselineDateRange`. Other top-level fields are rejected:
+Put all parameters in `query`. The only sibling is the optional `baselineDateRange`. Omit it to compare with the same window one week earlier.
```json
-{ "query": { "serviceNames": ["api"], "dateRange": { "date_from": "-1d" } } }
+{ "query": { "dateRange": { "date_from": "-24h" }, "severityLevels": ["error", "fatal"], "limit": 25 } }
```
-# When to use
+Each entry has:
-- **Incident triage (the primary loop):** set `query.dateRange` to the incident window. Omit `baselineDateRange` (defaults to the same window one week earlier) or set it to a known-good window just before the incident. The `new` and biggest `rate_shift` entries are your suspects; pivot to their raw lines with `query-logs`.
-- **Explain a spike:** when a count or sparkline shows a spike (e.g. from `logs-count-ranges`), set `query.dateRange` to the spike window and `baselineDateRange` to the window just before it — the top `new` and `rate_shift` entries are the explanation. This is one call; do not mine the two windows separately and diff them yourself.
-- **Post-deploy check:** current window = since the deploy; `baselineDateRange` = the same-length window just before it. New error-severity templates right after a deploy are the classic regression signature.
-- **"What changed this week?"** — current = `-1d`, baseline auto. Good periodic sweep for a service you own.
+- `classification`: `new`, `rate_shift`, `gone` or `unchanged` ("no confident claim").
+- `rate_ratio`: current rate / baseline rate, per second. 4.0 is 4x faster now.
+- `masked_example`: the template with variable parts masked. It can still hold literal text from the logs, so check it before you quote it.
+- `services`, `baseline_estimated_count`, and `pattern` with counts and `match_regex` / `match_patterns`.
+- `first_seen_ever`: the earliest time the pattern appears in the last 14 days. It tells "new today" from "new this week". Null on the body-mining fallback.
-## Pick the right tool
+Read the top level too:
-- Just summarize one window's content → `logs-patterns`.
-- Explain a _count_ change without needing message content → `logs-count-ranges` (cheaper).
-- Use **this** tool when you need to know _which messages_ are new or behaving differently between two periods.
+- `window`: the absolute UTC bounds that were compared.
+- `source` and `sampled`: `stored_patterns` gives exact counts. `body_mining` (`sampled: true`) gives estimates, and rare templates can be missing.
+- `baseline.total_count`: if it is 0 or small, every pattern looks new.
+- `next`: prefilled `query-logs` calls for the raw lines of the top suspects.
-# Reading the response
-
-Entries come sorted most-interesting-first: `new` (by volume), then `rate_shift` (by magnitude), then `gone`, then `unchanged`.
-
-- `classification` — trust the labels; the thresholds already handle sampling honesty:
- - `new` requires clearing a novelty floor (~1% volume share, or any error/fatal lines). Below the floor, absence from the baseline sample is not evidence of novelty.
- - `rate_shift` requires ≥2x change in per-second rate (windows of different lengths are normalized) _and_ enough raw samples on both sides.
- - `unchanged` means "no confident claim", not "provably identical".
-- `rate_ratio` — current rate / baseline rate. 4.0 = 4x faster now, 0.25 = quartered.
-- `pattern` — full pattern stats including `match_regex` / `match_literal`, so you can pivot straight to the matching lines (same recipe as `logs-patterns`: message regex filter + the pattern's services/severities).
-- **Check `baseline.total_count` before trusting a wall of `new` entries** — an empty or tiny baseline (logging only started recently, service didn't exist last week) makes everything look new.
-- Both windows are mined from samples (`sampled: true`), so counts are estimates and templates rarer than ~1 in 10,000 rows may be invisible in either window.
-
-Template identity across the two windows is fingerprint-based (literal content), so the miner rendering `User <*> not found` in one window and `User <num> not found` in the other still compares as one pattern rather than a false new+gone pair.
-
-# Parameters
-
-## query.dateRange
-
-The current (foreground) window — the period you are investigating. Same format as `logs-patterns`.
-
-## baselineDateRange
-
-Optional, sibling of `query` (not inside it). The comparison window. Omit for the default: the current window shifted back exactly one week, which absorbs daily/weekly volume cycles. Provide explicitly to compare against a pre-deploy or pre-incident period. It does not need to be the same length as the current window — rates are normalized per second.
-
-## query.severityLevels / query.serviceNames / query.searchTerm / query.filterGroup
-
-Same as `logs-patterns`; applied to **both** windows. Scoping by service is recommended — it prunes both scans and focuses the sample budget.
-
-# Examples
-
-## What changed during the incident vs. just before it
-
-```json
-{
- "query": {
- "dateRange": { "date_from": "2026-07-07T09:30:00Z", "date_to": "2026-07-07T10:30:00Z" },
- "serviceNames": ["checkout"]
- },
- "baselineDateRange": { "date_from": "2026-07-07T08:00:00Z", "date_to": "2026-07-07T09:00:00Z" }
-}
-```
-
-## What is new or different today vs. the same time last week
-
-```json
-{ "query": { "dateRange": { "date_from": "-1d" } } }
-```
-
-## Did the deploy change what the service logs?
-
-```json
-{
- "query": {
- "dateRange": { "date_from": "2026-07-07T14:00:00Z" },
- "serviceNames": ["api"]
- },
- "baselineDateRange": { "date_from": "2026-07-07T10:00:00Z", "date_to": "2026-07-07T14:00:00Z" }
-}
-```
+Scope `serviceNames` once you know the service.
diff --git a/products/logs/mcp/tools.yaml b/products/logs/mcp/tools.yaml
index f3f3cb8c835d..5e734508007a 100644
--- a/products/logs/mcp/tools.yaml
+++ b/products/logs/mcp/tools.yaml
@@ -453,6 +453,8 @@ tools:
description_file: ./prompts/logs-patterns-diff.md
response:
exclude:
+ - entries.*.pattern.pattern
+ - entries.*.pattern.services
- entries.*.pattern.examples
- entries.*.pattern.sparkline
- entries.*.pattern.count
diff --git a/products/tracing/mcp/tools.yaml b/products/tracing/mcp/tools.yaml
index 85ce5331213f..af54ba930202 100644
--- a/products/tracing/mcp/tools.yaml
+++ b/products/tracing/mcp/tools.yaml
@@ -81,6 +81,9 @@ tools:
description: >
List distinct service names that have emitted trace spans. Use to discover available services before
filtering spans by service name.
+ param_overrides:
+ dateRange:
+ cast: object-json-string
feature_flag: tracing
response:
include:
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index ea6cf183b53a..be7739dd4f38 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -9214,7 +9214,7 @@
}
},
"logs-patterns-diff": {
- "description": "Compare the log patterns of two time windows and return what changed: templates that are **new**, templates whose rate **shifted** (with magnitude, e.g. 4x), and templates that are **gone**. This is the single most useful call for incident triage — \"what is different about now vs. before it broke\" in one round trip, instead of mining two windows yourself and hand-matching templates.\n\nAll parameters go inside `query`, except the optional sibling `baselineDateRange`. Other top-level fields are rejected:\n\n```json\n{ \"query\": { \"serviceNames\": [\"api\"], \"dateRange\": { \"date_from\": \"-1d\" } } }\n```\n\n# When to use\n\n- **Incident triage (the primary loop):** set `query.dateRange` to the incident window. Omit `baselineDateRange` (defaults to the same window one week earlier) or set it to a known-good window just before the incident. The `new` and biggest `rate_shift` entries are your suspects; pivot to their raw lines with `query-logs`.\n- **Explain a spike:** when a count or sparkline shows a spike (e.g. from `logs-count-ranges`), set `query.dateRange` to the spike window and `baselineDateRange` to the window just before it — the top `new` and `rate_shift` entries are the explanation. This is one call; do not mine the two windows separately and diff them yourself.\n- **Post-deploy check:** current window = since the deploy; `baselineDateRange` = the same-length window just before it. New error-severity templates right after a deploy are the classic regression signature.\n- **\"What changed this week?\"** — current = `-1d`, baseline auto. Good periodic sweep for a service you own.\n\n## Pick the right tool\n\n- Just summarize one window's content → `logs-patterns`.\n- Explain a _count_ change without needing message content → `logs-count-ranges` (cheaper).\n- Use **this** tool when you need to know _which messages_ are new or behaving differently between two periods.\n\n# Reading the response\n\nEntries come sorted most-interesting-first: `new` (by volume), then `rate_shift` (by magnitude), then `gone`, then `unchanged`.\n\n- `classification` — trust the labels; the thresholds already handle sampling honesty:\n - `new` requires clearing a novelty floor (~1% volume share, or any error/fatal lines). Below the floor, absence from the baseline sample is not evidence of novelty.\n - `rate_shift` requires ≥2x change in per-second rate (windows of different lengths are normalized) _and_ enough raw samples on both sides.\n - `unchanged` means \"no confident claim\", not \"provably identical\".\n- `rate_ratio` — current rate / baseline rate. 4.0 = 4x faster now, 0.25 = quartered.\n- `pattern` — full pattern stats including `match_regex` / `match_literal`, so you can pivot straight to the matching lines (same recipe as `logs-patterns`: message regex filter + the pattern's services/severities).\n- **Check `baseline.total_count` before trusting a wall of `new` entries** — an empty or tiny baseline (logging only started recently, service didn't exist last week) makes everything look new.\n- Both windows are mined from samples (`sampled: true`), so counts are estimates and templates rarer than ~1 in 10,000 rows may be invisible in either window.\n\nTemplate identity across the two windows is fingerprint-based (literal content), so the miner rendering `User <*> not found` in one window and `User <num> not found` in the other still compares as one pattern rather than a false new+gone pair.\n\n# Parameters\n\n## query.dateRange\n\nThe current (foreground) window — the period you are investigating. Same format as `logs-patterns`.\n\n## baselineDateRange\n\nOptional, sibling of `query` (not inside it). The comparison window. Omit for the default: the current window shifted back exactly one week, which absorbs daily/weekly volume cycles. Provide explicitly to compare against a pre-deploy or pre-incident period. It does not need to be the same length as the current window — rates are normalized per second.\n\n## query.severityLevels / query.serviceNames / query.searchTerm / query.filterGroup\n\nSame as `logs-patterns`; applied to **both** windows. Scoping by service is recommended — it prunes both scans and focuses the sample budget.\n\n# Examples\n\n## What changed during the incident vs. just before it\n\n```json\n{\n \"query\": {\n \"dateRange\": { \"date_from\": \"2026-07-07T09:30:00Z\", \"date_to\": \"2026-07-07T10:30:00Z\" },\n \"serviceNames\": [\"checkout\"]\n },\n \"baselineDateRange\": { \"date_from\": \"2026-07-07T08:00:00Z\", \"date_to\": \"2026-07-07T09:00:00Z\" }\n}\n```\n\n## What is new or different today vs. the same time last week\n\n```json\n{ \"query\": { \"dateRange\": { \"date_from\": \"-1d\" } } }\n```\n\n## Did the deploy change what the service logs?\n\n```json\n{\n \"query\": {\n \"dateRange\": { \"date_from\": \"2026-07-07T14:00:00Z\" },\n \"serviceNames\": [\"api\"]\n },\n \"baselineDateRange\": { \"date_from\": \"2026-07-07T10:00:00Z\", \"date_to\": \"2026-07-07T14:00:00Z\" }\n}\n```",
+ "description": "Compare the log patterns of a current window with a baseline window. Use it for \"which error patterns are new or worse?\" in one call. Do not mine two windows and match templates yourself.\n\nPut all parameters in `query`. The only sibling is the optional `baselineDateRange`. Omit it to compare with the same window one week earlier.\n\n```json\n{ \"query\": { \"dateRange\": { \"date_from\": \"-24h\" }, \"severityLevels\": [\"error\", \"fatal\"], \"limit\": 25 } }\n```\n\nEach entry has:\n\n- `classification`: `new`, `rate_shift`, `gone` or `unchanged` (\"no confident claim\").\n- `rate_ratio`: current rate / baseline rate, per second. 4.0 is 4x faster now.\n- `masked_example`: the template with variable parts masked. It can still hold literal text from the logs, so check it before you quote it.\n- `services`, `baseline_estimated_count`, and `pattern` with counts and `match_regex` / `match_patterns`.\n- `first_seen_ever`: the earliest time the pattern appears in the last 14 days. It tells \"new today\" from \"new this week\". Null on the body-mining fallback.\n\nRead the top level too:\n\n- `window`: the absolute UTC bounds that were compared.\n- `source` and `sampled`: `stored_patterns` gives exact counts. `body_mining` (`sampled: true`) gives estimates, and rare templates can be missing.\n- `baseline.total_count`: if it is 0 or small, every pattern looks new.\n- `next`: prefilled `query-logs` calls for the raw lines of the top suspects.\n\nScope `serviceNames` once you know the service.",
"category": "Logs",
"feature": "logs",
"summary": "Diff log patterns between two windows",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 47e699059d06..cedd49bebc3c 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -9608,7 +9608,7 @@
}
},
"logs-patterns-diff": {
- "description": "Compare the log patterns of two time windows and return what changed: templates that are **new**, templates whose rate **shifted** (with magnitude, e.g. 4x), and templates that are **gone**. This is the single most useful call for incident triage — \"what is different about now vs. before it broke\" in one round trip, instead of mining two windows yourself and hand-matching templates.\n\nAll parameters go inside `query`, except the optional sibling `baselineDateRange`. Other top-level fields are rejected:\n\n```json\n{ \"query\": { \"serviceNames\": [\"api\"], \"dateRange\": { \"date_from\": \"-1d\" } } }\n```\n\n# When to use\n\n- **Incident triage (the primary loop):** set `query.dateRange` to the incident window. Omit `baselineDateRange` (defaults to the same window one week earlier) or set it to a known-good window just before the incident. The `new` and biggest `rate_shift` entries are your suspects; pivot to their raw lines with `query-logs`.\n- **Explain a spike:** when a count or sparkline shows a spike (e.g. from `logs-count-ranges`), set `query.dateRange` to the spike window and `baselineDateRange` to the window just before it — the top `new` and `rate_shift` entries are the explanation. This is one call; do not mine the two windows separately and diff them yourself.\n- **Post-deploy check:** current window = since the deploy; `baselineDateRange` = the same-length window just before it. New error-severity templates right after a deploy are the classic regression signature.\n- **\"What changed this week?\"** — current = `-1d`, baseline auto. Good periodic sweep for a service you own.\n\n## Pick the right tool\n\n- Just summarize one window's content → `logs-patterns`.\n- Explain a _count_ change without needing message content → `logs-count-ranges` (cheaper).\n- Use **this** tool when you need to know _which messages_ are new or behaving differently between two periods.\n\n# Reading the response\n\nEntries come sorted most-interesting-first: `new` (by volume), then `rate_shift` (by magnitude), then `gone`, then `unchanged`.\n\n- `classification` — trust the labels; the thresholds already handle sampling honesty:\n - `new` requires clearing a novelty floor (~1% volume share, or any error/fatal lines). Below the floor, absence from the baseline sample is not evidence of novelty.\n - `rate_shift` requires ≥2x change in per-second rate (windows of different lengths are normalized) _and_ enough raw samples on both sides.\n - `unchanged` means \"no confident claim\", not \"provably identical\".\n- `rate_ratio` — current rate / baseline rate. 4.0 = 4x faster now, 0.25 = quartered.\n- `pattern` — full pattern stats including `match_regex` / `match_literal`, so you can pivot straight to the matching lines (same recipe as `logs-patterns`: message regex filter + the pattern's services/severities).\n- **Check `baseline.total_count` before trusting a wall of `new` entries** — an empty or tiny baseline (logging only started recently, service didn't exist last week) makes everything look new.\n- Both windows are mined from samples (`sampled: true`), so counts are estimates and templates rarer than ~1 in 10,000 rows may be invisible in either window.\n\nTemplate identity across the two windows is fingerprint-based (literal content), so the miner rendering `User <*> not found` in one window and `User <num> not found` in the other still compares as one pattern rather than a false new+gone pair.\n\n# Parameters\n\n## query.dateRange\n\nThe current (foreground) window — the period you are investigating. Same format as `logs-patterns`.\n\n## baselineDateRange\n\nOptional, sibling of `query` (not inside it). The comparison window. Omit for the default: the current window shifted back exactly one week, which absorbs daily/weekly volume cycles. Provide explicitly to compare against a pre-deploy or pre-incident period. It does not need to be the same length as the current window — rates are normalized per second.\n\n## query.severityLevels / query.serviceNames / query.searchTerm / query.filterGroup\n\nSame as `logs-patterns`; applied to **both** windows. Scoping by service is recommended — it prunes both scans and focuses the sample budget.\n\n# Examples\n\n## What changed during the incident vs. just before it\n\n```json\n{\n \"query\": {\n \"dateRange\": { \"date_from\": \"2026-07-07T09:30:00Z\", \"date_to\": \"2026-07-07T10:30:00Z\" },\n \"serviceNames\": [\"checkout\"]\n },\n \"baselineDateRange\": { \"date_from\": \"2026-07-07T08:00:00Z\", \"date_to\": \"2026-07-07T09:00:00Z\" }\n}\n```\n\n## What is new or different today vs. the same time last week\n\n```json\n{ \"query\": { \"dateRange\": { \"date_from\": \"-1d\" } } }\n```\n\n## Did the deploy change what the service logs?\n\n```json\n{\n \"query\": {\n \"dateRange\": { \"date_from\": \"2026-07-07T14:00:00Z\" },\n \"serviceNames\": [\"api\"]\n },\n \"baselineDateRange\": { \"date_from\": \"2026-07-07T10:00:00Z\", \"date_to\": \"2026-07-07T14:00:00Z\" }\n}\n```",
+ "description": "Compare the log patterns of a current window with a baseline window. Use it for \"which error patterns are new or worse?\" in one call. Do not mine two windows and match templates yourself.\n\nPut all parameters in `query`. The only sibling is the optional `baselineDateRange`. Omit it to compare with the same window one week earlier.\n\n```json\n{ \"query\": { \"dateRange\": { \"date_from\": \"-24h\" }, \"severityLevels\": [\"error\", \"fatal\"], \"limit\": 25 } }\n```\n\nEach entry has:\n\n- `classification`: `new`, `rate_shift`, `gone` or `unchanged` (\"no confident claim\").\n- `rate_ratio`: current rate / baseline rate, per second. 4.0 is 4x faster now.\n- `masked_example`: the template with variable parts masked. It can still hold literal text from the logs, so check it before you quote it.\n- `services`, `baseline_estimated_count`, and `pattern` with counts and `match_regex` / `match_patterns`.\n- `first_seen_ever`: the earliest time the pattern appears in the last 14 days. It tells \"new today\" from \"new this week\". Null on the body-mining fallback.\n\nRead the top level too:\n\n- `window`: the absolute UTC bounds that were compared.\n- `source` and `sampled`: `stored_patterns` gives exact counts. `body_mining` (`sampled: true`) gives estimates, and rare templates can be missing.\n- `baseline.total_count`: if it is 0 or small, every pattern looks new.\n- `next`: prefilled `query-logs` calls for the raw lines of the top suspects.\n\nScope `serviceNames` once you know the service.",
"category": "Logs",
"feature": "logs",
"summary": "Diff log patterns between two windows",
diff --git a/services/mcp/scripts/generate-tools.ts b/services/mcp/scripts/generate-tools.ts
index a643a0aef6a8..c489c303d6a5 100644
--- a/services/mcp/scripts/generate-tools.ts
+++ b/services/mcp/scripts/generate-tools.ts
@@ -464,6 +464,7 @@ function operationIdToPascal(operationId: string): string {
const CAST_HELPERS = {
'string-int': 'castStringToInt',
'boolean-string': 'castBooleanToString',
+ 'object-json-string': 'castObjectToJsonString',
} as const
interface SchemaComposition {
diff --git a/services/mcp/scripts/yaml-config-schema.ts b/services/mcp/scripts/yaml-config-schema.ts
index 89c09c9b4487..24801041399e 100644
--- a/services/mcp/scripts/yaml-config-schema.ts
+++ b/services/mcp/scripts/yaml-config-schema.ts
@@ -109,7 +109,7 @@ export const ToolConfigSchema = z
* Mutually exclusive with `input_schema` and `schema_ref` (those
* fully replace the schema; cast composes with the existing one).
*/
- cast: z.enum(['string-int', 'boolean-string']).optional(),
+ cast: z.enum(['string-int', 'boolean-string', 'object-json-string']).optional(),
/**
* Alternate key names accepted for this param and normalized to it
* before validation — for identifier params agents guess different
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 10c963d327f0..234f0e1ae241 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -64016,6 +64016,36 @@ export namespace Schemas {
project_name: string;
}
+ /**
+ * Prefilled `query` object for that tool. Pass it as is or adjust it.
+ */
+ export type LogsAgentNextCallQuery = { [key: string]: unknown };
+
+ export interface LogsAgentNextCall {
+ /** MCP tool to call next, e.g. query-logs or logs-context. */
+ tool: string;
+ /** One line on what the follow-up call answers. */
+ why: string;
+ /** Prefilled `query` object for that tool. Pass it as is or adjust it. */
+ query: LogsAgentNextCallQuery;
+ }
+
+ export interface LogsAgentWindowBounds {
+ /** Window start, ISO 8601 UTC with a Z suffix (inclusive). */
+ from: string;
+ /** Window end, ISO 8601 UTC with a Z suffix (exclusive). */
+ to: string;
+ }
+
+ export interface LogsAgentWindow {
+ /** Absolute bounds the server used for the current window. */
+ current: LogsAgentWindowBounds;
+ /** Absolute bounds the server used for the baseline window, when there is one. */
+ baseline?: LogsAgentWindowBounds;
+ /** Always "UTC". */
+ timezone: string;
+ }
+
export interface LogsAlertFilters {
filterGroup?: PropertyGroupFilter | null;
serviceNames?: string[] | null;
@@ -88973,6 +89003,18 @@ export namespace Schemas {
funnels_query: unknown;
}
+ /**
+ * * `stored_patterns` - Stored Patterns
+ * * `body_mining` - Body Mining
+ */
+ export type PatternsDiffSourceEnum = typeof PatternsDiffSourceEnum[keyof typeof PatternsDiffSourceEnum];
+
+
+ export const PatternsDiffSourceEnum = {
+ StoredPatterns: 'stored_patterns',
+ BodyMining: 'body_mining',
+ } as const;
+
export interface PauseResponse {
/** Always 'paused'. */
status: string;
@@ -117496,6 +117538,15 @@ export namespace Schemas {
} as const;
export interface _LogPatternDiffEntry {
+ /** The template with variable parts masked. */
+ masked_example: string;
+ /** Up to 4 services with this pattern. */
+ services: string[];
+ /**
+ * Earliest 5-minute bucket (UTC) with this pattern, up to 14 days back. Null on body mining.
+ * @nullable
+ */
+ first_seen_ever: string | null;
/** "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.
*
* * `new` - new
@@ -117808,9 +117859,33 @@ export namespace Schemas {
sessionId?: string;
}
+ export interface _LogsPatternsDiffBody {
+ /** Date range to mine patterns from. Defaults to last hour. */
+ dateRange?: _DateRange;
+ /** Filter by log severity levels before mining. */
+ severityLevels?: SeverityLevelsEnum[];
+ /** Restrict mining to these service names. */
+ serviceNames?: string[];
+ /** Full-text search term to filter log bodies before mining. */
+ searchTerm?: string;
+ /** Property filters applied before mining. Same shape as the query-logs endpoint. */
+ filterGroup?: _LogPropertyFilter[];
+ /** Scope mining 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. */
+ personId?: string;
+ /** Scope mining 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. */
+ sessionId?: string;
+ /**
+ * Return at most this many entries, most interesting first. Omit for all. Sets `truncated`.
+ * @minimum 1
+ * @maximum 500
+ * @nullable
+ */
+ limit?: number | null;
+ }
+
export interface _LogsPatternsDiffRequest {
/** 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. */
- query: _LogsPatternsBody;
+ query: _LogsPatternsDiffBody;
/** 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. */
baselineDateRange?: _DateRange;
}
@@ -117863,6 +117938,26 @@ export namespace Schemas {
}
export interface _LogsPatternsDiffResponse {
+ /** Absolute UTC bounds of the current and baseline windows. */
+ window: LogsAgentWindow;
+ /** stored_patterns when both windows have ≥99% of rows on the same stored version, else body_mining.
+ *
+ * * `stored_patterns` - Stored Patterns
+ * * `body_mining` - Body Mining */
+ source: PatternsDiffSourceEnum;
+ /**
+ * Stored pattern version, null for mining.
+ * @nullable
+ */
+ pattern_version: number | null;
+ /** True on the body-mining fallback: counts are sample estimates. */
+ sampled: boolean;
+ /** True when `limit` cut the entry list. */
+ truncated: boolean;
+ /** Caveats that limit what the diff shows. */
+ notes: string[];
+ /** Prefilled query-logs calls for the top new or shifted patterns. */
+ next: LogsAgentNextCall[];
/** 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. */
entries: _LogPatternDiffEntry[];
/** Mining metadata for the current window. */
diff --git a/services/mcp/src/generated/logs/api.ts b/services/mcp/src/generated/logs/api.ts
index 019aa0a7158c..559a377d1d91 100644
--- a/services/mcp/src/generated/logs/api.ts
+++ b/services/mcp/src/generated/logs/api.ts
@@ -6329,6 +6329,8 @@ export const LogsPatternsDiffCreateParams = () => zod.object({
),
})
+export const logsPatternsDiffCreateBodyQueryOneLimitMax = 500
+
export const LogsPatternsDiffCreateBody = () => zod.object({
query: zod
.object({
@@ -6423,6 +6425,12 @@ export const LogsPatternsDiffCreateBody = () => zod.object({
.describe(
"Scope mining 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."
),
+ limit: zod
+ .number()
+ .min(1)
+ .max(logsPatternsDiffCreateBodyQueryOneLimitMax)
+ .nullish()
+ .describe('Return at most this many entries, most interesting first. Omit for all. Sets `truncated`.'),
})
.describe(
'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.'
diff --git a/services/mcp/src/lib/build-tool-result.ts b/services/mcp/src/lib/build-tool-result.ts
index 4c1ab3a0c31c..050160b9f07e 100644
--- a/services/mcp/src/lib/build-tool-result.ts
+++ b/services/mcp/src/lib/build-tool-result.ts
@@ -257,7 +257,7 @@ export function buildToolResultPayload(opts: BuildToolResultOptions): ToolResult
structuredContentOnly,
footers,
discoveryHint: discoveryHint?.kind,
- resultEmpty: isEmptyToolResult(handlerResult),
+ resultEmpty: isEmptyToolResult(handlerResult, toolName),
})
if (hasUiResource && !suppressStructuredContent) {
payload.structuredContent = structuredContent as Record<string, unknown>
diff --git a/services/mcp/src/lib/discovery-hints.ts b/services/mcp/src/lib/discovery-hints.ts
index afadc8d5ba1d..46ecd88ff82f 100644
--- a/services/mcp/src/lib/discovery-hints.ts
+++ b/services/mcp/src/lib/discovery-hints.ts
@@ -33,6 +33,12 @@ const EMPTY_STATE_HINTS: Record<string, string> = {
'No log rows matched. If this project has never ingested logs, load the `instrument-logs` skill to start shipping them. Otherwise widen the `dateRange` or drop filters — `logs-count` is a cheap way to check whether any logs exist at all.',
'query-session-recordings-list':
'No recordings matched. If session replay has never captured anything here, load the `diagnosing-missing-recordings` skill to check SDK setup, sampling, and capture settings. Otherwise widen the date range or loosen the filters.',
+ 'logs-context':
+ 'No logs matched around this anchor. Widen `padding` or the `dateRange`, or drop `severityLevels`. If the anchor is a trace, check that the services write `trace_id` on their logs — `logs-count` with a `trace_id` filter is a cheap check.',
+ 'apm-service-health':
+ 'No spans matched. If this project has never ingested traces, the services are not instrumented yet. Otherwise widen the `dateRange`, or drop `environment` and `serviceNames` — `apm-services-list` shows the services that sent spans.',
+ 'logs-group-by':
+ 'No groups matched. Widen the `dateRange` or drop filters. If the group key is an attribute, check its name and source with `logs-attributes-list`.',
'get-llm-total-costs-for-project':
'No LLM cost data found. If AI observability is not capturing `$ai_generation` events yet, load the `instrument-llm-analytics` skill to wire it up. Otherwise widen the date range.',
}
@@ -49,6 +55,12 @@ const RELATED_CAPABILITY_HINTS: Record<string, string> = {
'Related: this insight can go on a dashboard (`building-a-dashboard` skill) or be delivered to email/Slack on a schedule (`managing-subscriptions` skill).',
}
+const PRIMARY_RESULT_KEYS: Record<string, string> = {
+ 'apm-service-health': 'services',
+ 'logs-context': 'timeline',
+ 'logs-group-by': 'groups',
+}
+
/**
* Empty means "zero rows", in the two shapes the registered tools return:
* a bare array, or the standardized `{ results: [...] }` envelope produced by
@@ -56,13 +68,14 @@ const RELATED_CAPABILITY_HINTS: Record<string, string> = {
* other shape is treated as non-empty — hints only register tools whose
* shapes are known, so this never has to guess.
*/
-export function isEmptyToolResult(handlerResult: unknown): boolean {
+export function isEmptyToolResult(handlerResult: unknown, toolName?: string): boolean {
if (Array.isArray(handlerResult)) {
return handlerResult.length === 0
}
if (typeof handlerResult === 'object' && handlerResult !== null) {
- const results = (handlerResult as Record<string, unknown>).results
- return Array.isArray(results) && results.length === 0
+ const key = (toolName && PRIMARY_RESULT_KEYS[toolName]) || 'results'
+ const rows = (handlerResult as Record<string, unknown>)[key]
+ return Array.isArray(rows) && rows.length === 0
}
return false
}
@@ -87,7 +100,7 @@ export interface DiscoveryHint {
* when the result is empty, the related-capability hint otherwise.
*/
export function getDiscoveryHint({ toolName, handlerResult }: DiscoveryHintInput): DiscoveryHint | undefined {
- if (isEmptyToolResult(handlerResult)) {
+ if (isEmptyToolResult(handlerResult, toolName)) {
const text = EMPTY_STATE_HINTS[toolName]
return text ? { kind: 'empty_state', text } : undefined
}
diff --git a/services/mcp/src/lib/tool-error-hints.ts b/services/mcp/src/lib/tool-error-hints.ts
index e5c79e18b741..8ab73ec217e3 100644
--- a/services/mcp/src/lib/tool-error-hints.ts
+++ b/services/mcp/src/lib/tool-error-hints.ts
@@ -37,8 +37,22 @@ const LOGS_QUERY_URL_FRAGMENTS = [
'/logs/count-ranges/',
'/logs/services/',
'/logs/sparkline/',
+ '/logs/group-by/',
+ '/logs/context/',
+ '/logs/environments/',
]
+const TRACING_QUERY_RECOVERY_HINT = [
+ 'This tracing query failed server-side. The most common cause is a query that scans too much data and times out — not a bug in your filters.',
+ '',
+ 'Narrow the query and retry:',
+ '1. Shorten `dateRange` (e.g. `-1h` instead of `-1d`).',
+ '2. Add `serviceNames` — discover them with `apm-services-list` — or add a filter to `filterGroup`.',
+ '3. Start from `apm-service-health` for per-service rates and latency, then drill into one service with `apm-spans-aggregate` before you pull spans with `query-apm-spans`.',
+].join('\n')
+
+const TRACING_QUERY_URL_FRAGMENT = '/tracing/spans/'
+
/**
* The survey create/update endpoint returns a 5xx when a structured parameter
* arrives as a JSON-encoded string instead of an object or array. Some MCP
@@ -92,6 +106,9 @@ export function getToolRecoveryHint({ url, status, retryAfterSeconds }: Recovery
if (url && LOGS_QUERY_URL_FRAGMENTS.some((fragment) => url.includes(fragment))) {
return LOGS_QUERY_RECOVERY_HINT
}
+ if (url && url.includes(TRACING_QUERY_URL_FRAGMENT)) {
+ return TRACING_QUERY_RECOVERY_HINT
+ }
if (url && SURVEY_WRITE_URL_RE.test(url)) {
return SURVEY_WRITE_RECOVERY_HINT
}
diff --git a/services/mcp/src/tools/cast-helpers.ts b/services/mcp/src/tools/cast-helpers.ts
index f6ff7a27206b..7309fb08264b 100644
--- a/services/mcp/src/tools/cast-helpers.ts
+++ b/services/mcp/src/tools/cast-helpers.ts
@@ -47,6 +47,9 @@ export const castStringToInt = (v: unknown): unknown => {
*/
export const castBooleanToString = (v: unknown): unknown => (typeof v === 'boolean' ? String(v) : v)
+export const castObjectToJsonString = (v: unknown): unknown =>
+ v !== null && typeof v === 'object' && !Array.isArray(v) ? JSON.stringify(v) : v
+
/**
* Normalize alternate key spellings to a canonical param name before validation.
*
diff --git a/services/mcp/src/tools/exec.ts b/services/mcp/src/tools/exec.ts
index 0118a76b4b78..9172ada683bf 100644
--- a/services/mcp/src/tools/exec.ts
+++ b/services/mcp/src/tools/exec.ts
@@ -2106,7 +2106,7 @@ export function createExecTool(
}
const durationMs = Date.now() - startedAt
// The text path below builds no payload, so emptiness is reported from here.
- const resultShape = isEmptyToolResult(result) ? { result_empty: true } : {}
+ const resultShape = isEmptyToolResult(result, tool.name) ? { result_empty: true } : {}
const formattedOverride =
result !== null && typeof result === 'object'
? (result as Record<string, unknown>)[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]
diff --git a/services/mcp/src/tools/generated/logs.ts b/services/mcp/src/tools/generated/logs.ts
index 95526c0edbfc..156cf597ef9a 100644
--- a/services/mcp/src/tools/generated/logs.ts
+++ b/services/mcp/src/tools/generated/logs.ts
@@ -752,6 +752,8 @@ const logsPatternsDiff = (): ToolBase<
body,
})
const filtered = omitResponseFields(result, [
+ 'entries.*.pattern.pattern',
+ 'entries.*.pattern.services',
'entries.*.pattern.examples',
'entries.*.pattern.sparkline',
'entries.*.pattern.count',
diff --git a/services/mcp/src/tools/generated/tracing.ts b/services/mcp/src/tools/generated/tracing.ts
index 65eb6c091572..22252070771d 100644
--- a/services/mcp/src/tools/generated/tracing.ts
+++ b/services/mcp/src/tools/generated/tracing.ts
@@ -4,6 +4,7 @@ import { z } from 'zod'
import type { Schemas } from '@/api/generated'
import * as orvalSchemas from '@/generated/tracing/api'
import { withUiApp } from '@/resources/ui-apps'
+import { castObjectToJsonString } from '@/tools/cast-helpers'
import { withPostHogUrl, pickResponseFields, type WithPostHogUrl } from '@/tools/tool-utils'
import type { Context, ToolBase, ZodObjectAny } from '@/tools/types'
@@ -91,7 +92,11 @@ const apmAttributesList = (): ToolBase<
const ApmServicesListSchema = () => {
const TracingSpansServiceNamesRetrieveQueryParams = orvalSchemas.TracingSpansServiceNamesRetrieveQueryParams()
- return TracingSpansServiceNamesRetrieveQueryParams
+ return TracingSpansServiceNamesRetrieveQueryParams.extend({
+ dateRange: z
+ .preprocess(castObjectToJsonString, TracingSpansServiceNamesRetrieveQueryParams.shape['dateRange'])
+ .optional(),
+ })
}
const apmServicesList = (): ToolBase<
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/logs-patterns-diff.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/logs-patterns-diff.json
index 96ea9a57c285..0a865d55bb4a 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/logs-patterns-diff.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/logs-patterns-diff.json
@@ -105,6 +105,19 @@
},
"type": "array"
},
+ "limit": {
+ "anyOf": [
+ {
+ "maximum": 500,
+ "minimum": 1,
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Return at most this many entries, most interesting first. Omit for all. Sets `truncated`."
+ },
"personId": {
"description": "Scope mining 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.",
"type": "string"
diff --git a/services/mcp/tests/unit/cast-helpers.test.ts b/services/mcp/tests/unit/cast-helpers.test.ts
index 476215974816..81ddbc26a937 100644
--- a/services/mcp/tests/unit/cast-helpers.test.ts
+++ b/services/mcp/tests/unit/cast-helpers.test.ts
@@ -12,6 +12,7 @@ import { z } from 'zod'
import {
castBooleanToString,
+ castObjectToJsonString,
castStringToInt,
normalizeParamAliases,
readParamAliases,
@@ -62,6 +63,33 @@ describe('castStringToInt', () => {
})
})
+describe('castObjectToJsonString', () => {
+ const schema = z.preprocess(castObjectToJsonString, z.string())
+
+ it('JSON-encodes a plain object', () => {
+ expect(schema.parse({ date_from: '-24h' })).toBe('{"date_from":"-24h"}')
+ })
+
+ it('gives the same value for an object and its JSON-encoded string', () => {
+ expect(schema.parse({ date_from: '-1h', date_to: null })).toBe(
+ schema.parse(JSON.stringify({ date_from: '-1h', date_to: null }))
+ )
+ })
+
+ it('passes through strings untouched', () => {
+ expect(schema.parse('{"date_from": "-1h"}')).toBe('{"date_from": "-1h"}')
+ })
+
+ it.each([
+ ['array', ['-1h']],
+ ['number', 7],
+ ['boolean', true],
+ ['null', null],
+ ] as const)('passes non-object input through to zod: %s', (_label, input) => {
+ expect(() => schema.parse(input)).toThrow()
+ })
+})
+
describe('castBooleanToString', () => {
const schema = z.preprocess(castBooleanToString, z.string())
diff --git a/services/mcp/tests/unit/discovery-hints.test.ts b/services/mcp/tests/unit/discovery-hints.test.ts
index a701b760317b..f5c16ff56898 100644
--- a/services/mcp/tests/unit/discovery-hints.test.ts
+++ b/services/mcp/tests/unit/discovery-hints.test.ts
@@ -58,6 +58,23 @@ describe('getDiscoveryHint', () => {
expect(getDiscoveryHint({ toolName, handlerResult: { results: [] } })?.text).toContain(skillName)
})
+ it.each([
+ ['logs-context', { anchor: {}, timeline: [] }],
+ ['apm-service-health', { summary: {}, services: [] }],
+ ['logs-group-by', { groups: [] }],
+ ])('treats an empty primary array as empty for %s', (toolName, handlerResult) => {
+ const hint = getDiscoveryHint({ toolName, handlerResult })
+
+ expect(hint?.kind).toBe('empty_state')
+ expect(hint?.text).toContain('dateRange')
+ })
+
+ it('does not fire the empty-state hint when logs-context has timeline rows', () => {
+ const hint = getDiscoveryHint({ toolName: 'logs-context', handlerResult: { timeline: [{ body: 'x' }] } })
+
+ expect(hint?.kind).not.toBe('empty_state')
+ })
+
it('cross-sells subscriptions and dashboards after insight creation', () => {
const hint = getDiscoveryHint({ toolName: 'insight-create', handlerResult: { id: 1, short_id: 'abc' } })
diff --git a/services/mcp/tests/unit/generate-tools.test.ts b/services/mcp/tests/unit/generate-tools.test.ts
index 9561e3318a68..d7e48440231c 100644
--- a/services/mcp/tests/unit/generate-tools.test.ts
+++ b/services/mcp/tests/unit/generate-tools.test.ts
@@ -2260,6 +2260,40 @@ describe('generateToolCode with confirmed_action', () => {
})
})
+describe('object-json-string cast', () => {
+ const resolved = (): ResolvedOperation =>
+ makeResolved({
+ method: 'GET',
+ path: '/api/projects/{project_id}/things/service-names/',
+ operation: {
+ operationId: 'things_service_names_retrieve',
+ parameters: [
+ { in: 'path', name: 'project_id', required: true, schema: { type: 'string' } },
+ { in: 'query', name: 'dateRange', required: false, schema: { type: 'string' } },
+ ],
+ },
+ })
+
+ it('wraps the param with castObjectToJsonString and imports the helper', () => {
+ const result = generateToolCode(
+ 'things-service-names',
+ {
+ operation: 'things_service_names_retrieve',
+ enabled: true,
+ param_overrides: { dateRange: { cast: 'object-json-string' } },
+ },
+ resolved(),
+ defaultCategory,
+ makeSpec(),
+ new Set<string>(),
+ stubGetQuerySchema
+ )
+ const collapsed = result.code.replace(/\s+/g, ' ')
+ expect(collapsed).toContain('z.preprocess(castObjectToJsonString')
+ expect(result.castHelperImports.has('castObjectToJsonString')).toBe(true)
+ })
+})
+
describe('optional param with state fallback', () => {
const resolved = (): ResolvedOperation =>
makeResolved({
diff --git a/services/mcp/tests/unit/tool-error-hints.test.ts b/services/mcp/tests/unit/tool-error-hints.test.ts
index 20cfed8f9aca..9df19decb5a2 100644
--- a/services/mcp/tests/unit/tool-error-hints.test.ts
+++ b/services/mcp/tests/unit/tool-error-hints.test.ts
@@ -43,6 +43,34 @@ describe('getToolRecoveryHint', () => {
expect(getToolRecoveryHint({ url: LOGS_QUERY_URL })).not.toBeUndefined()
})
+ it.each([
+ 'https://us.posthog.com/api/projects/2/tracing/spans/query/',
+ 'https://us.posthog.com/api/projects/2/tracing/spans/count/',
+ 'https://us.posthog.com/api/projects/2/tracing/spans/aggregate/',
+ 'https://us.posthog.com/api/projects/2/tracing/spans/service-health/',
+ ])('returns the tracing narrow-and-retry hint for a 5xx on %s', (url: string) => {
+ const hint = getToolRecoveryHint({ url, status: 500 })
+
+ expect(hint).not.toBeUndefined()
+ expect(hint).toContain('serviceNames')
+ expect(hint).toContain('apm-service-health')
+ expect(hint).not.toContain('logs-count-ranges')
+ })
+
+ it('does not fire the tracing hint for a 400 on a tracing endpoint', () => {
+ expect(
+ getToolRecoveryHint({ url: 'https://us.posthog.com/api/projects/2/tracing/spans/count/', status: 400 })
+ ).toBeUndefined()
+ })
+
+ it('also fires the logs hint for the new logs aggregate endpoints', () => {
+ for (const path of ['group-by', 'context', 'environments']) {
+ expect(
+ getToolRecoveryHint({ url: `https://us.posthog.com/api/projects/2/logs/${path}/`, status: 500 })
+ ).not.toBeUndefined()
+ }
+ })
+
it.each([
'https://us.posthog.com/api/projects/2/surveys/',
'https://us.posthog.com/api/projects/2/surveys/018f-abc/',