:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(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.pyindex 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 Callablefrom typing import TYPE_CHECKINGfrom 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 ClickHouseQueryTimeOutfrom posthog.hogql_queries.query_runner import ExecutionMode+from products.logs.backend.agent_window import utc_iso, window_echofrom products.logs.backend.log_patterns import ERROR_SEVERITIES, _env, pattern_fingerprint+from products.logs.backend.logs_query_runner import fail_fast_aggregate_settingsfrom products.logs.backend.patterns_query_runner import PatternsQueryRunnerif 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 = 5000def _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: DateRpreceding hour. The current window is resolved once and the baseline derived from theresolved 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: DateRdate_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 = resultsentries = 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.pyindex 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_selectfrom posthog.hogql.query import execute_hogql_queryfrom posthog.clickhouse.client.connection import Workload+from posthog.clickhouse.client.limit import app_org_concurrency_slot+from posthog.dataclasses import frozenfrom posthog.exceptions import ClickHouseQueryTimeOutfrom posthog.hogql_queries.query_runner import AnalyticsQueryRunnerfrom 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], LogsQueryRunndef _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.versionif 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_propertydef _stored_patterns_enabled(self) -> bool:# only_evaluate_locally keeps this check off the network: it gates an interactive query, sodiff --git a/products/logs/backend/presentation/views/agent_fields.py b/products/logs/backend/presentation/views/agent_fields.pynew file mode 100644index 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.pyindex 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 PatternsQueryRunnerfrom products.logs.backend.presentation.views.alerts_api import LogsAlertViewSetfrom products.logs.backend.presentation.views.explain import LogExplainViewSetfrom 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 LogsRetentionRuleViewSetfrom products.logs.backend.presentation.views.sampling_api import LogsSamplingRuleViewSetfrom 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.pynew file mode 100644index 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.pyindex 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 jsonimport datetime as dt+from typing import Anyimport time_machinefrom posthog.test.base import APIBaseTest, ClickhouseTestMixinfrom unittest import TestCase+from unittest.mock import MagicMock, patchfrom 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 ClickHouseQueryTimeOutfrom 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.pynew file mode 100644index 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.tsindex 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.tsindex 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 constexport 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.tsindex 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.mdindex 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.yamlindex 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.mdresponse:exclude:+ - entries.*.pattern.pattern+ - entries.*.pattern.services- entries.*.pattern.examples- entries.*.pattern.sparkline- entries.*.pattern.countdiff --git a/products/tracing/mcp/tools.yaml b/products/tracing/mcp/tools.yamlindex 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 beforefiltering spans by service name.+ param_overrides:+ dateRange:+ cast: object-json-stringfeature_flag: tracingresponse:include:diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 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.jsonindex 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.tsindex 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 constinterface SchemaComposition {diff --git a/services/mcp/scripts/yaml-config-schema.ts b/services/mcp/scripts/yaml-config-schema.tsindex 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 differentdiff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 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.tsindex 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.tsindex 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): ToolResultstructuredContentOnly,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.tsindex 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.tsindex 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 }: Recoveryif (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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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/',