: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(aio): trace clusters chip (#124360)
Carlos Marchal0212673ed017
diff --git a/frontend/snapshots.yml b/frontend/snapshots.ymlindex 85feaaf0c871..a5c0ce1e5885 100644--- a/frontend/snapshots.yml+++ b/frontend/snapshots.yml@@ -9734,6 +9734,18 @@ snapshots:hash: v1.k794b7964.909ba48aa0b1f664036a5f22fad341be78fc8c1a058a8117ed2e3c870c18a7c3.foFLxGwVGgGhafMdp8x2w6_GQp8BBEed6O5W5zizT0Ascenes-app-ai-observability-trace-view-thread-turn--with-error--light:hash: v1.k794b7964.d5676030474b4b9abadf20b5788257628abdbb126f3f41a84ccba7d938790c65.qaUZ9puKwLwSRbLEoqGeK5MDWRqju8VXMkfMxfRux1g+ scenes-app-ai-observability-trace-view-trace-clusters-chip--long-title-narrow--dark:+ hash: v1.k794b7964.ebf027a92a8f43ec515312da1b4286ddaf4782d52655299c97331f3bd426f3b2.4ua-bph2pPzQVpl9Pd_fvFFKyGqdkqMS_WpBUvGkezw+ scenes-app-ai-observability-trace-view-trace-clusters-chip--long-title-narrow--light:+ hash: v1.k794b7964.0c754add4cfc3432dfac28b4a49fc792a95cb19192e9bc48e4a24274a7ad487f.aQhCp0OvSnKdtA7cQiI3yV9HHhzWDprRto6MIQJ-lCU+ scenes-app-ai-observability-trace-view-trace-clusters-chip--one-cluster--dark:+ hash: v1.k794b7964.e1df871d8a62ba336783211e4bfa75b52033eaddd20187f2356128e5fd403234.1gxTfHIBNhIphxFbIcsD1RLcpzi-A9XhBqdqHWUj7Zk+ scenes-app-ai-observability-trace-view-trace-clusters-chip--one-cluster--light:+ hash: v1.k794b7964.b782747748032acd2e500665044ec1ba9a7d0a8d6b938345c3fa27568d95e81e.bFXms0xCSqAJm9yb_9XcFxUx4g0axpcEKEU4V2za39w+ scenes-app-ai-observability-trace-view-trace-clusters-chip--outlier-only--dark:+ hash: v1.k794b7964.05885eb7d3eae322d187a0668c0b522c78980eb4abccbe112e44dbacd1d31881.A8aALTHV5MJNDvAshbl9_nuWkh3KNfoiiztuWKrYLKc+ scenes-app-ai-observability-trace-view-trace-clusters-chip--outlier-only--light:+ hash: v1.k794b7964.7fb34c00afcd35d9ee68f4b715bc558966d3a25d95bd0b89370f1b47d61c0fe4.OMnpT-y_Me0S92srt0iYGNFFvnczxucni9d4GiK01rYscenes-app-ai-observability-trace-view-trace-header--default--dark:hash: v1.k794b7964.89f74988daa805a5decedf40f47256dc0776cf10499f7927bccec49753e659b8.BAtU5Cxiu3j-JRB9Z_iy032Q7TVs-L0M01FCCizn3n0scenes-app-ai-observability-trace-view-trace-header--default--light:@@ -9807,9 +9819,9 @@ snapshots:scenes-app-ai-observability-trace-view-trace-summary-bar--long-slug-id--light:hash: v1.k794b7964.91510acc263da4572cdd54a1072d89d308d9d12f3a689353abcbef13bdf452ca.pBf3neAQB4BRTb9-4IRDujW7q1F_GF-pTHV3UHv9PnQscenes-app-ai-observability-trace-view-trace-summary-bar--narrow--dark:- hash: v1.k794b7964.daebccd14686a4ffa02937c8621dc74845153b053e2c5581ac18055fc85c2011.Jwh3UjTBshXuWKYsYsjgLLcwNkROjdAxPLk5xY7oQys+ hash: v1.k794b7964.ee5d03658549f32a225e94021f63169560c9c5e360f6deae750a621efadfcedc.zL6G2ExwgKkeQVCD9aAuseAfHRQxOnodZkXVt0huPRwscenes-app-ai-observability-trace-view-trace-summary-bar--narrow--light:- hash: v1.k794b7964.89c5f822021e4c9c6581b1867d29be28fa87cf638297617fe1dd9f46c87310df.mx9UHOPdDLvPVcF_QQQRTgNGytxi_bTrB_AJBimtWjQ+ hash: v1.k794b7964.acb3645733c46cf841a3da15259dbee824c6046b7c6db42bf451a4ca992340eb.C6XyBCxowGHCRIqzsNYsziyhPPdXoTh9xlpfEzrq67Iscenes-app-ai-observability-trace-view-trace-summary-bar--narrow-with-long-git-branch--dark:hash: v1.k794b7964.306fabde159267a2ffad36e356b4db293663b87a2ca8bf9c53575230fe4ccd41.-1ojgmfWHNK7Mv4-rNw_HlYOul55PvTX7utdFjsqDFsscenes-app-ai-observability-trace-view-trace-summary-bar--narrow-with-long-git-branch--light:@@ -9818,6 +9830,10 @@ snapshots:hash: v1.k794b7964.b0dd60321acfc66eff4b4fe61c0123016d6ef51e83d18e1a33989d71056cf4c4.rhGXCqb0ZHRrzjcvMjSYO0_vKIrG0vZRA9yacMU9g4Ascenes-app-ai-observability-trace-view-trace-summary-bar--short-id--light:hash: v1.k794b7964.bbfc40a18f0a11428e95c34e2783676e785e9e7730f88d7efb397ad11b954fad.A7axwdw43M17lj8qq6VSnmn7SyIXVP2oOIQzdvKA9m8+ scenes-app-ai-observability-trace-view-trace-summary-bar--with-clusters--dark:+ hash: v1.k794b7964.a3b7a5c14340ec662a1043e5a65d2eb56dd66fd2f2a0187b9c874bdb7ad893bf.3_XP-tXdrX74OsDEVSlZMbC_Wgyc6-iLKL1dKE6O7VM+ scenes-app-ai-observability-trace-view-trace-summary-bar--with-clusters--light:+ hash: v1.k794b7964.e9becda69994d79e3a5ee167c52bf1d07a44ea40a7aaffcba57dd0d19ad50e84.e0WXJXsPwMemdJMxRjobOhDw4Mw42DfxlTSUCy_tJ2Ascenes-app-ai-observability-trace-view-trace-summary-bar--with-feedback--dark:hash: v1.k794b7964.4ee4b41df55c5bc9f386036bb5c7bf684ca90215cb9046f62375c4d8eb2defd4.Xu2hxbSf7Oc5ztiyAnhnTkeZCdhT-YnBK5mMKOAfG8Escenes-app-ai-observability-trace-view-trace-summary-bar--with-feedback--light:diff --git a/frontend/src/initKea.ts b/frontend/src/initKea.tsindex c021759ec4c1..128ca0ef25b4 100644--- a/frontend/src/initKea.ts+++ b/frontend/src/initKea.ts@@ -137,6 +137,7 @@ const ERROR_FILTER_ALLOW_LIST_BY_LOGIC_PATH: Record<string, string> = {updateProviderKey: 'products.ai_observability.settings.llmProviderKeysLogic',deleteProviderKey: 'products.ai_observability.settings.llmProviderKeysLogic',loadEvaluationResults: 'products.ai_observability.frontend.redesign.trace.traceViewLogic', // The trace view's Evals tab shows the error+ loadClusters: 'products.ai_observability.frontend.redesign.trace.traceClustersLogic', // The trace view hides the clusters chiploadTraceFeedback: 'products.ai_observability.frontend.redesign.trace.traceFeedbackLogic', // The trace view's Feedback mode shows the errorloadSearchResults: 'products.ai_observability.frontend.redesign.trace.traceSearchLogic', // The trace view's search box shows the error// The trace view's Summary mode shows the errordiff --git a/products/ai_observability/backend/facade/api.py b/products/ai_observability/backend/facade/api.pyindex f2abf859d088..435b96cfe02b 100644--- a/products/ai_observability/backend/facade/api.py+++ b/products/ai_observability/backend/facade/api.py@@ -16,6 +16,8 @@ from ..logic.evaluations.period import ()from ..logic.evaluations.runs import RunOutcome, load_runsfrom ..logic.evaluations.score_distribution import load_score_distribution, score_buckets+from ..logic.traces.cluster_queries import ClusterRunWindow, can_read_clusters, load_cluster_runs+from ..logic.traces.clusters import ClusterMemberships, TraceClusterfrom ..logic.traces.evaluation_result import EvaluationResultfrom ..logic.traces.evaluation_result_queries import load_evaluation_results, load_output_configsfrom ..logic.traces.evaluation_summary import EvaluationSummary@@ -265,6 +267,36 @@ def _to_evaluation_result(result: EvaluationResult) -> contracts.TraceEvaluation)+def is_usable_trace_start(created_at: datetime) -> bool:+ try:+ ClusterRunWindow.for_trace(created_at)+ except OverflowError:+ return False+ return True+++def get_trace_clusters(team: Team, user: User | None, trace_id: str, created_at: datetime) -> contracts.TraceClusters:+ if not can_read_clusters(team, user):+ return contracts.TraceClusters(clusters=[])+ runs = load_cluster_runs(team, user, trace_id, ClusterRunWindow.for_trace(created_at))+ return contracts.TraceClusters(+ clusters=[_to_trace_cluster(cluster) for cluster in ClusterMemberships.of(trace_id, runs).clusters]+ )+++def _to_trace_cluster(cluster: TraceCluster) -> contracts.TraceCluster:+ return contracts.TraceCluster(+ run_id=cluster.run_id,+ run_at=cluster.run_at,+ job_id=cluster.job_id,+ job_name=cluster.job_name,+ cluster_id=cluster.cluster_id,+ title=cluster.title,+ description=cluster.description,+ is_outlier=cluster.is_outlier,+ )++def get_trace_feedback(team: Team, user: User | None, trace_id: str, timestamp_hint: datetime | None) -> contracts.TraceFeedback:diff --git a/products/ai_observability/backend/facade/contracts.py b/products/ai_observability/backend/facade/contracts.pyindex d4be062c8a6c..2d1d407b9bed 100644--- a/products/ai_observability/backend/facade/contracts.py+++ b/products/ai_observability/backend/facade/contracts.py@@ -169,6 +169,26 @@ class TraceEvaluationResults(Contract):summary: TraceEvaluationSummary+class TraceCluster(Contract):+ run_id: str = Field(+ description="The clustering run that put the trace in this cluster. The cluster page is addressed by this id and the cluster id."+ )+ run_at: datetime = Field(description="When the run finished.")+ job_id: str | None = Field(description="The clustering job the run belongs to, null for a run without a job.")+ job_name: str | None+ cluster_id: int = Field(description="The cluster's id within its run. -1 is the run's outliers.")+ title: str | None+ description: str | None+ is_outlier: bool = Field(description="The trace fit no cluster in this run.")+++class TraceClusters(Contract):+ clusters: list[TraceCluster] = Field(+ description="The clusters that list the trace: for each clustering job, the newest scheduled run that lists it. "+ "Manual runs are left out. Clusters come before outliers, then newest first."+ )++class TraceFeedbackScore(Contract):id: strname: str | Nonediff --git a/products/ai_observability/backend/logic/traces/cluster_queries.py b/products/ai_observability/backend/logic/traces/cluster_queries.pynew file mode 100644index 000000000000..ecfc7ef5c2e0--- /dev/null+++ b/products/ai_observability/backend/logic/traces/cluster_queries.py@@ -0,0 +1,132 @@+import re+from collections.abc import Sequence+from datetime import UTC, datetime, timedelta+from typing import Any, Self++from posthog.hogql import ast+from posthog.hogql.context import HogQLContext+from posthog.hogql.database.database import Database+from posthog.hogql.query import execute_hogql_query++from posthog.clickhouse.query_tagging import Product, tag_queries, tags_context+from posthog.clickhouse.workload import Workload+from posthog.dataclasses import frozen+from posthog.models import Team, User+from posthog.temporal.ai_observability.trace_clustering.constants import DEFAULT_LOOKBACK_DAYS, EVENT_NAME++from products.access_control.backend.facade.user_access_control import UserAccessControl++CLUSTER_RUNS_LIMIT = 100+# Runs pick items by when their summary was embedded, so a run can list a trace long after the trace started.+# The embedding lands within a day of the trace, a scheduled run looks back DEFAULT_LOOKBACK_DAYS from its end,+# and the run is emitted within an hour of its end. The reach covers that sum with most of a day to spare.+CLUSTER_RUN_REACH = timedelta(days=DEFAULT_LOOKBACK_DAYS + 2)+# Every JSON serializer on the write and read paths writes these characters verbatim, so the raw text contains the id.+_VERBATIM_SAFE_ID = re.compile(r"[A-Za-z0-9_:-]+")+++@frozen+class ClusterRunWindow:+ start: datetime+ end: datetime++ @classmethod+ def for_trace(cls, created_at: datetime) -> Self:+ start = created_at.astimezone(UTC).replace(hour=0, minute=0, second=0, microsecond=0)+ return cls(start=start, end=created_at + CLUSTER_RUN_REACH)+++@frozen+class ClusterRunRow:+ uuid: str+ timestamp: datetime+ run_id: str | None+ job_id: str | None+ job_name: str | None+ clusters: str | None+++def _property(name: str) -> ast.Field:+ return ast.Field(chain=["properties", name])+++def _runs_query(trace_id: str, window: ClusterRunWindow) -> ast.SelectQuery:+ conditions: list[ast.Expr] = [+ ast.CompareOperation(+ op=ast.CompareOperationOp.Eq,+ left=ast.Field(chain=["event"]),+ right=ast.Constant(value=EVENT_NAME),+ ),+ ast.CompareOperation(+ op=ast.CompareOperationOp.GtEq, left=ast.Field(chain=["timestamp"]), right=ast.Constant(value=window.start)+ ),+ ast.CompareOperation(+ op=ast.CompareOperationOp.Lt, left=ast.Field(chain=["timestamp"]), right=ast.Constant(value=window.end)+ ),+ ]+ if _VERBATIM_SAFE_ID.fullmatch(trace_id):+ # A substring check skips parsing runs that cannot list the trace; membership is decided after parsing.+ conditions.append(+ ast.CompareOperation(+ op=ast.CompareOperationOp.Gt,+ left=ast.Call(name="position", args=[_property("$ai_clusters"), ast.Constant(value=trace_id)]),+ right=ast.Constant(value=0),+ )+ )+ return ast.SelectQuery(+ select=[+ ast.Field(chain=["uuid"]),+ ast.Field(chain=["timestamp"]),+ _property("$ai_clustering_run_id"),+ _property("$ai_clustering_job_id"),+ _property("$ai_clustering_job_name"),+ _property("$ai_clusters"),+ ],+ select_from=ast.JoinExpr(table=ast.Field(chain=["events"])),+ where=ast.And(exprs=conditions),+ order_by=[ast.OrderExpr(expr=ast.Field(chain=["timestamp"]), order="DESC")],+ limit_by=ast.LimitByExpr(n=ast.Constant(value=1), exprs=[ast.Field(chain=["uuid"])]),+ limit=ast.Constant(value=CLUSTER_RUNS_LIMIT),+ )+++def _raw(value: Any) -> str | None:+ return None if value is None else str(value)+++def _run_row(values: Sequence[Any]) -> ClusterRunRow:+ uuid, timestamp, run_id, job_id, job_name, clusters = values+ return ClusterRunRow(+ uuid=str(uuid),+ timestamp=timestamp,+ run_id=_raw(run_id),+ job_id=_raw(job_id),+ job_name=_raw(job_name),+ clusters=_raw(clusters),+ )+++def load_cluster_runs(+ team: Team, user: User | None, trace_id: str, window: ClusterRunWindow+) -> tuple[ClusterRunRow, ...]:+ name = "ai_trace_clusters"+ with tags_context(product=Product.LLM_ANALYTICS):+ tag_queries(name=name)+ response = execute_hogql_query(+ query=_runs_query(trace_id, window),+ team=team,+ user=user,+ query_type=name,+ workload=Workload.ONLINE,+ context=HogQLContext(+ team_id=team.pk, team=team, user=user, database=Database.create_for_posthog_tables(team)+ ),+ )+ return tuple(_run_row(values) for values in response.results or [])+++def can_read_clusters(team: Team, user: User | None) -> bool:+ # Clusters have their own access control, apart from the llm_analytics access that opens the trace.+ return user is None or UserAccessControl(user=user, team=team).check_access_level_for_resource(+ "ai_observability_clusters", "viewer"+ )diff --git a/products/ai_observability/backend/logic/traces/clusters.py b/products/ai_observability/backend/logic/traces/clusters.pynew file mode 100644index 000000000000..520650a3af49--- /dev/null+++ b/products/ai_observability/backend/logic/traces/clusters.py@@ -0,0 +1,91 @@+import re+import json+from collections.abc import Iterator, Mapping, Sequence+from datetime import datetime+from typing import Self++from posthog.dataclasses import frozen+from posthog.temporal.ai_observability.trace_clustering.constants import NOISE_CLUSTER_ID++from .cluster_queries import ClusterRunRow+from .trace_queries import read_text++# Run ids read {team_id}_{level}_{YYYYMMDD}_{HHMMSS}[_{job_id}][_{run_label}], and only a manual admin run sets a label.+_UNLABELLED_RUN_ID = re.compile(r"\d+_[a-z]+_\d{8}_\d{6}(?:_(?P<job_id>[^_]+))?")+++@frozen+class TraceCluster:+ run_id: str+ run_at: datetime+ job_id: str | None+ job_name: str | None+ cluster_id: int+ title: str | None+ description: str | None++ @property+ def is_outlier(self) -> bool:+ return self.cluster_id == NOISE_CLUSTER_ID+++def _parsed_clusters(raw: str | None) -> list[object]:+ if raw is None:+ return []+ try:+ clusters = json.loads(raw)+ except ValueError:+ return []+ return clusters if isinstance(clusters, list) else []+++def _is_manual(run: ClusterRunRow) -> bool:+ match = _UNLABELLED_RUN_ID.fullmatch(read_text(run.run_id) or "")+ return match is None or match["job_id"] != read_text(run.job_id)+++def _memberships(trace_id: str, run: ClusterRunRow) -> Iterator[TraceCluster]:+ run_id = read_text(run.run_id)+ if run_id is None:+ return+ for cluster in _parsed_clusters(run.clusters):+ if not isinstance(cluster, Mapping):+ continue+ cluster_id = cluster.get("cluster_id")+ traces = cluster.get("traces")+ if isinstance(cluster_id, bool) or not isinstance(cluster_id, int) or not isinstance(traces, Mapping):+ continue+ if trace_id in traces:+ yield TraceCluster(+ run_id=run_id,+ run_at=run.timestamp,+ job_id=read_text(run.job_id),+ job_name=read_text(run.job_name),+ cluster_id=cluster_id,+ title=read_text(cluster.get("title")),+ description=read_text(cluster.get("description")),+ )+++@frozen+class ClusterMemberships:+ clusters: tuple[TraceCluster, ...]++ @classmethod+ def of(cls, trace_id: str, runs: Sequence[ClusterRunRow]) -> Self:+ # Scheduled jobs rerun daily over overlapping windows, so each job keeps only its newest run that lists the trace.+ # A manual run can reuse a job's id with its own parameters, so it must not displace the job's scheduled run.+ newest_by_job: dict[str, TraceCluster] = {}+ for run in runs:+ if _is_manual(run):+ continue+ for membership in _memberships(trace_id, run):+ job = membership.job_id or ""+ current = newest_by_job.get(job)+ if current is None or membership.run_at > current.run_at:+ newest_by_job[job] = membership+ return cls(+ clusters=tuple(+ sorted(newest_by_job.values(), key=lambda c: (c.is_outlier, -c.run_at.timestamp(), c.run_id))+ )+ )diff --git a/products/ai_observability/backend/presentation/views.py b/products/ai_observability/backend/presentation/views.pyindex d78f8452a3b5..b71ae0058564 100644--- a/products/ai_observability/backend/presentation/views.py+++ b/products/ai_observability/backend/presentation/views.py@@ -37,6 +37,17 @@ class TraceQuerySerializer(serializers.Serializer):return value+class TraceClustersQuerySerializer(serializers.Serializer):+ created_at = serializers.DateTimeField(+ help_text="When the trace started, as the trace resource's createdAt. Bounds which clustering runs are read."+ )++ def validate_created_at(self, value: datetime) -> datetime:+ if not api.is_usable_trace_start(value):+ raise serializers.ValidationError("Trace start is out of range.")+ return value++class TraceSearchQuerySerializer(TraceQuerySerializer):q = serializers.CharField(max_length=200, help_text="The text to find in the trace's steps, ignoring case.")@@ -66,7 +77,7 @@ class TraceSummaryRequestSerializer(serializers.Serializer):class TraceViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):scope_object = "llm_analytics"- scope_object_read_actions = ["retrieve", "node", "evaluations", "feedback", "search", "summary"]+ scope_object_read_actions = ["retrieve", "node", "evaluations", "clusters", "feedback", "search", "summary"]scope_object_write_actions = ["request_summary"]# Traces are project-wide data, so a grant on a single llm_analytics object must not open them.requires_resource_level_access = True@@ -148,6 +159,34 @@ class TraceViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):results = self._read(request, lambda user, _hint: api.get_trace_evaluation_results(self.team, user, trace_id))return Response(results.model_dump(mode="json", by_alias=True))+ @validated_request(+ query_serializer=TraceClustersQuerySerializer,+ parameters=[TRACE_ID_PARAMETER],+ responses={+ 200: OpenApiResponse(response=contracts.TraceClusters),+ 400: OpenApiResponse(description="The created_at parameter or the encoded trace id is malformed."),+ 429: THROTTLED_RESPONSE,+ },+ operation_id="ai_observability_traces_clusters_retrieve",+ )+ @action(+ detail=True,+ methods=["GET"],+ url_path="clusters",+ required_scopes=["llm_analytics:read", "ai_observability_clusters:read"],+ )+ def clusters(self, request: ValidatedRequest, pk: str, **kwargs: Any) -> Response:+ """The clusters that list this trace, from the newest scheduled run of each clustering job that lists it."""+ try:+ trace_id = decode_trace_id_segment(pk)+ except MalformedTraceIdSegmentError:+ return Response({"detail": "Malformed encoded trace id."}, status=status.HTTP_400_BAD_REQUEST)+ created_at = request.validated_query_data["created_at"]+ clusters = self._read(+ request, lambda user, _hint: api.get_trace_clusters(self.team, user, trace_id, created_at)+ )+ return Response(clusters.model_dump(mode="json", by_alias=True))+@validated_request(query_serializer=TraceQuerySerializer,parameters=[TRACE_ID_PARAMETER],diff --git a/products/ai_observability/backend/tests/logic/traces/rows.py b/products/ai_observability/backend/tests/logic/traces/rows.pyindex dd898bd3e335..948bf84916be 100644--- a/products/ai_observability/backend/tests/logic/traces/rows.py+++ b/products/ai_observability/backend/tests/logic/traces/rows.py@@ -1,9 +1,11 @@-from collections.abc import Mapping-from datetime import UTC, datetime+import json+from collections.abc import Mapping, Sequence+from datetime import UTC, datetime, timedeltafrom typing import Anyfrom posthog.models import Team+from products.ai_observability.backend.logic.traces.cluster_queries import ClusterRunRowfrom products.ai_observability.backend.logic.traces.evaluation_result_queries import EvaluationResultRowfrom products.ai_observability.backend.logic.traces.trace_queries import FeedbackEventRow, TraceEventRow@@ -94,3 +96,82 @@ def make_evaluation_result_event("timestamp": timestamp,"properties": {"$ai_trace_id": trace_id, "$ai_evaluation_result": True, **(properties or {})},}+++CLUSTERING_JOB_ID = "0192f2a4-5c1e-7000-8000-0000000c1a01"+++def make_cluster(+ cluster_id: int,+ trace_ids: Sequence[str],+ title: str = "Restoring archived projects",+ description: str = "Users ask to bring back a deleted project.",+) -> dict[str, object]:+ return {+ "cluster_id": cluster_id,+ "size": len(trace_ids),+ "title": title,+ "description": description,+ "traces": {+ trace_id: {+ "distance_to_centroid": 0.2,+ "rank": rank,+ "x": 0.1,+ "y": -0.3,+ "timestamp": "2026-09-01T10:00:00+00:00",+ "trace_id": trace_id,+ "generation_id": None,+ }+ for rank, trace_id in enumerate(trace_ids)+ },+ "centroid": [0.1, 0.2],+ "centroid_x": 0.1,+ "centroid_y": -0.3,+ "metrics": None,+ }+++def cluster_json(*clusters: Mapping[str, object]) -> str:+ return json.dumps(list(clusters))+++def make_cluster_run_row(**overrides: Any) -> ClusterRunRow:+ fields: dict[str, Any] = {+ "uuid": "run-event-1",+ "timestamp": T0 + timedelta(hours=17),+ "run_id": f"1_trace_20260902_030000_{CLUSTERING_JOB_ID}",+ "job_id": CLUSTERING_JOB_ID,+ "job_name": "Support conversations",+ "clusters": cluster_json(make_cluster(0, ["trace-1", "trace-2"])),+ }+ return ClusterRunRow(**{**fields, **overrides})+++def make_cluster_run_event(+ *,+ uuid: str,+ team: Team,+ timestamp: datetime,+ clusters: Sequence[Mapping[str, object]],+ run_id: str = "1_trace_20260902_030000",+ job_id: str = "",+ job_name: str = "",+ event: str = "$ai_trace_clusters",+) -> dict[str, object]:+ return {+ "event": event,+ "event_uuid": uuid,+ "distinct_id": f"clustering_trace_{team.pk}",+ "team": team,+ "timestamp": timestamp,+ "properties": {+ "$ai_clustering_run_id": run_id,+ "$ai_clustering_level": "trace",+ "$ai_clustering_job_id": job_id,+ "$ai_clustering_job_name": job_name,+ "$ai_window_start": (timestamp - timedelta(days=7)).isoformat(),+ "$ai_window_end": timestamp.isoformat(),+ "$ai_total_items_analyzed": 2,+ "$ai_clusters": list(clusters),+ },+ }diff --git a/products/ai_observability/backend/tests/logic/traces/test_cluster_queries.py b/products/ai_observability/backend/tests/logic/traces/test_cluster_queries.pynew file mode 100644index 000000000000..01a215bcf33b--- /dev/null+++ b/products/ai_observability/backend/tests/logic/traces/test_cluster_queries.py@@ -0,0 +1,112 @@+from datetime import UTC, datetime, timedelta++from posthog.test.base import BaseTest, ClickhouseTestMixin++from parameterized import parameterized++from posthog.models import Team+from posthog.models.event.util import bulk_create_events++from products.ai_observability.backend.logic.traces.cluster_queries import (+ CLUSTER_RUN_REACH,+ ClusterRunWindow,+ load_cluster_runs,+)+from products.ai_observability.backend.logic.traces.clusters import ClusterMemberships++from .rows import T0, make_cluster, make_cluster_run_event++LISTING = "00000000-0000-0000-0000-0000000c1001"+OTHER = "00000000-0000-0000-0000-0000000c1002"+++def test_the_window_starts_on_the_traces_day_and_reaches_past_the_scheduled_lookback() -> None:+ created_at = datetime(2026, 8, 12, 23, 30, tzinfo=UTC)++ window = ClusterRunWindow.for_trace(created_at)++ assert (window.start, window.end) == (datetime(2026, 8, 12, tzinfo=UTC), created_at + CLUSTER_RUN_REACH)+++class TestLoadClusterRuns(ClickhouseTestMixin, BaseTest):+ @parameterized.expand(+ [+ ("a uuid", "0192b3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b", [LISTING]),+ ("a slug", "support-chat-42", [LISTING]),+ ("non-ASCII", "naïve-trace", [LISTING, OTHER]),+ ("a slash", "run/42", [LISTING, OTHER]),+ ("quotes", 'id "quoted"', [LISTING, OTHER]),+ ("dots", "trace.with.dots", [LISTING, OTHER]),+ ("LIKE wildcards", "50%_off", [LISTING, OTHER]),+ ("a trailing newline", "trace-1\n", [LISTING, OTHER]),+ ]+ )+ def test_finds_runs_that_list_the_trace(self, _name: str, trace_id: str, read: list[str]) -> None:+ bulk_create_events(+ [+ make_cluster_run_event(+ uuid=LISTING,+ team=self.team,+ timestamp=T0 + timedelta(days=1),+ run_id="1_trace_20260902_030000",+ clusters=[make_cluster(2, ["other-trace", trace_id], title="Billing questions")],+ ),+ make_cluster_run_event(+ uuid=OTHER,+ team=self.team,+ timestamp=T0 + timedelta(hours=12),+ run_id="1_trace_20260901_220000",+ clusters=[make_cluster(0, ["other-trace"])],+ ),+ ]+ )++ rows = load_cluster_runs(self.team, None, trace_id, ClusterRunWindow.for_trace(T0))++ assert [row.uuid for row in rows] == read+ assert [(c.run_id, c.cluster_id) for c in ClusterMemberships.of(trace_id, rows).clusters] == [+ ("1_trace_20260902_030000", 2)+ ]++ def test_reads_only_runs_emitted_in_the_window(self) -> None:+ other_team = Team.objects.create(organization=self.organization, name="other")+ listing = [make_cluster(1, ["trace-1"])]+ before_the_day = "00000000-0000-0000-0000-0000000c2001"+ same_day = "00000000-0000-0000-0000-0000000c2002"+ last_day = "00000000-0000-0000-0000-0000000c2003"+ past_the_reach = "00000000-0000-0000-0000-0000000c2004"+ generation_level = "00000000-0000-0000-0000-0000000c2005"+ other_teams = "00000000-0000-0000-0000-0000000c2006"+ bulk_create_events(+ [+ make_cluster_run_event(+ uuid=before_the_day,+ team=self.team,+ timestamp=datetime(2026, 8, 31, 23, tzinfo=UTC),+ clusters=listing,+ ),+ make_cluster_run_event(+ uuid=same_day, team=self.team, timestamp=datetime(2026, 9, 1, 2, tzinfo=UTC), clusters=listing+ ),+ make_cluster_run_event(+ uuid=last_day, team=self.team, timestamp=datetime(2026, 9, 9, 20, tzinfo=UTC), clusters=listing+ ),+ make_cluster_run_event(+ uuid=past_the_reach, team=self.team, timestamp=T0 + CLUSTER_RUN_REACH, clusters=listing+ ),+ make_cluster_run_event(+ uuid=generation_level,+ team=self.team,+ timestamp=datetime(2026, 9, 2, 3, tzinfo=UTC),+ clusters=listing,+ event="$ai_generation_clusters",+ ),+ make_cluster_run_event(+ uuid=other_teams, team=other_team, timestamp=datetime(2026, 9, 2, 3, tzinfo=UTC), clusters=listing+ ),+ ]+ )++ rows = load_cluster_runs(self.team, None, "trace-1", ClusterRunWindow.for_trace(T0))++ assert [row.uuid for row in rows] == [last_day, same_day]diff --git a/products/ai_observability/backend/tests/logic/traces/test_clusters.py b/products/ai_observability/backend/tests/logic/traces/test_clusters.pynew file mode 100644index 000000000000..be5acdbf9a3e--- /dev/null+++ b/products/ai_observability/backend/tests/logic/traces/test_clusters.py@@ -0,0 +1,148 @@+from datetime import timedelta++from parameterized import parameterized++from products.ai_observability.backend.logic.traces.clusters import ClusterMemberships++from .rows import T0, cluster_json, make_cluster, make_cluster_run_row++JOB_A = "0192f2a4-5c1e-7000-8000-0000000c1a0a"+JOB_B = "0192f2a4-5c1e-7000-8000-0000000c1a0b"+++def test_finds_the_cluster_whose_traces_list_the_trace() -> None:+ row = make_cluster_run_row(+ clusters=cluster_json(make_cluster(0, ["trace-2"]), make_cluster(3, ["trace-1"], title="Billing questions"))+ )++ [membership] = ClusterMemberships.of("trace-1", [row]).clusters++ assert (membership.cluster_id, membership.title, membership.is_outlier, membership.job_name) == (+ 3,+ "Billing questions",+ False,+ "Support conversations",+ )+++ [+ ("a longer id", make_cluster(0, ["trace-10"])),+ ("the id in the title", make_cluster(0, ["trace-2"], title="Retries after trace-1 failed")),+ ]+)+def test_a_near_match_is_not_a_membership(_name: str, near: dict[str, object]) -> None:+ assert ClusterMemberships.of("trace-1", [make_cluster_run_row(clusters=cluster_json(near))]).clusters == ()+++def test_keeps_the_newest_scheduled_run_of_each_job() -> None:+ runs = [+ make_cluster_run_row(+ run_id=f"1_trace_20260905_120000_{JOB_A}_retry-tuning",+ job_id=JOB_A,+ job_name="Support conversations",+ timestamp=T0 + timedelta(days=4),+ clusters=cluster_json(make_cluster(9, ["trace-1"])),+ ),+ make_cluster_run_row(+ run_id=f"1_trace_20260903_030000_{JOB_A}",+ job_id=JOB_A,+ job_name="Support conversations",+ timestamp=T0 + timedelta(days=2),+ clusters=cluster_json(make_cluster(4, ["trace-1"])),+ ),+ make_cluster_run_row(+ run_id=f"1_trace_20260902_030000_{JOB_B}",+ job_id=JOB_B,+ job_name="Agent runs",+ timestamp=T0 + timedelta(days=1),+ clusters=cluster_json(make_cluster(1, ["trace-1"])),+ ),+ make_cluster_run_row(+ run_id=f"1_trace_20260904_030000_{JOB_A}",+ job_id=JOB_A,+ job_name="Support conversations",+ timestamp=T0 + timedelta(days=3),+ clusters=cluster_json(make_cluster(2, ["trace-1"])),+ ),+ make_cluster_run_row(+ run_id=f"1_trace_20260902_030000_{JOB_A}",+ job_id=JOB_A,+ job_name="Support conversations",+ timestamp=T0 + timedelta(days=1),+ clusters=cluster_json(make_cluster(0, ["trace-1"])),+ ),+ ]++ clusters = ClusterMemberships.of("trace-1", runs).clusters++ assert [(c.run_id, c.job_id, c.cluster_id) for c in clusters] == [+ (f"1_trace_20260904_030000_{JOB_A}", JOB_A, 2),+ (f"1_trace_20260902_030000_{JOB_B}", JOB_B, 1),+ ]+++def test_runs_without_a_job_count_as_one_job() -> None:+ runs = [+ make_cluster_run_row(run_id="1_trace_20260901_030000", job_id="", job_name="", timestamp=T0),+ make_cluster_run_row(+ run_id="1_trace_20260902_030000", job_id="", job_name="", timestamp=T0 + timedelta(days=1)+ ),+ make_cluster_run_row(+ run_id="1_trace_20260903_120000_retry-tuning", job_id="", job_name="", timestamp=T0 + timedelta(days=2)+ ),+ ]++ [membership] = ClusterMemberships.of("trace-1", runs).clusters++ assert (membership.run_id, membership.job_id, membership.job_name) == ("1_trace_20260902_030000", None, None)+++def test_outliers_come_after_clusters() -> None:+ runs = [+ make_cluster_run_row(+ run_id=f"1_trace_20260904_030000_{JOB_A}",+ job_id=JOB_A,+ timestamp=T0 + timedelta(days=3),+ clusters=cluster_json(make_cluster(0, ["trace-2"]), make_cluster(-1, ["trace-1"], title="Outliers")),+ ),+ make_cluster_run_row(+ run_id=f"1_trace_20260902_030000_{JOB_B}",+ job_id=JOB_B,+ timestamp=T0 + timedelta(days=1),+ clusters=cluster_json(make_cluster(1, ["trace-1"])),+ ),+ ]++ clusters = ClusterMemberships.of("trace-1", runs).clusters++ assert [(c.cluster_id, c.job_id, c.is_outlier) for c in clusters] == [(1, JOB_B, False), (-1, JOB_A, True)]+++ [+ ("no clusters", None),+ ("not JSON", "[{"),+ ("not a list", '{"cluster_id": 0}'),+ ("a cluster without traces", '[{"cluster_id": 0, "title": "Billing questions"}]'),+ ("a cluster id that is not a number", '[{"cluster_id": "zero", "traces": {"trace-1": {}}}]'),+ ]+)+def test_skips_what_it_cannot_read(_name: str, clusters: str | None) -> None:+ good = make_cluster_run_row(run_id="1_trace_20260901_030000", job_id="", timestamp=T0 + timedelta(hours=1))+ bad = make_cluster_run_row(clusters=clusters)++ assert [m.run_id for m in ClusterMemberships.of("trace-1", [bad, good]).clusters] == ["1_trace_20260901_030000"]++[email protected]([("missing", None), ("empty", "")])+def test_a_run_without_an_id_is_skipped(_name: str, run_id: str | None) -> None:+ assert ClusterMemberships.of("trace-1", [make_cluster_run_row(run_id=run_id)]).clusters == ()+++def test_an_empty_title_reads_as_none() -> None:+ row = make_cluster_run_row(clusters=cluster_json(make_cluster(5, ["trace-1"], title="", description="")))++ [membership] = ClusterMemberships.of("trace-1", [row]).clusters++ assert (membership.title, membership.description) == (None, None)diff --git a/products/ai_observability/backend/tests/test_facade_api.py b/products/ai_observability/backend/tests/test_facade_api.pyindex 3a3b97ccd4a0..862b7ac7264d 100644--- a/products/ai_observability/backend/tests/test_facade_api.py+++ b/products/ai_observability/backend/tests/test_facade_api.py@@ -32,7 +32,13 @@ from products.ai_observability.backend.logic.traces.trace_queries import LoadedTfrom products.ai_observability.backend.models.evaluations import Evaluationfrom products.event_definitions.backend.models.property_definition import PropertyDefinition-from .logic.traces.rows import make_evaluation_result_event, make_row+from .logic.traces.rows import (+ CLUSTERING_JOB_ID,+ make_cluster,+ make_cluster_run_event,+ make_evaluation_result_event,+ make_row,+)from .property_access import hide_event_propertyT0 = datetime(2026, 9, 1, 10, 0, tzinfo=UTC)@@ -201,6 +207,69 @@ class TestGetTraceEvaluationResults(ClickhouseTestMixin, BaseTest):assert [(node.node_id, node.outcome) for node in results.summary.nodes] == [("trace-1", "fail")]+class TestGetTraceClusters(ClickhouseTestMixin, BaseTest):+ def _run(+ self,+ uuid: str,+ clusters: list[dict[str, object]],+ *,+ days_after: int = 1,+ run_id: str = "1_trace_20260902_030000",+ job_id: str = "",+ job_name: str = "",+ ) -> dict[str, object]:+ return make_cluster_run_event(+ uuid=uuid,+ team=self.team,+ timestamp=T0 + timedelta(days=days_after),+ clusters=clusters,+ run_id=run_id,+ job_id=job_id,+ job_name=job_name,+ )++ def test_returns_the_clusters_that_list_the_trace(self) -> None:+ bulk_create_events(+ [+ self._run(+ "00000000-0000-0000-0000-0000000c3001",+ [make_cluster(3, ["trace-1"], title="Billing questions")],+ run_id=f"1_trace_20260902_030000_{CLUSTERING_JOB_ID}",+ job_id=CLUSTERING_JOB_ID,+ job_name="Support conversations",+ ),+ self._run(+ "00000000-0000-0000-0000-0000000c3002",+ [make_cluster(0, ["trace-2"]), make_cluster(-1, ["trace-1"], title="Outliers")],+ days_after=2,+ run_id="1_trace_20260903_030000",+ ),+ ]+ )++ clusters = api.get_trace_clusters(self.team, self.user, "trace-1", T0).clusters++ assert [(c.cluster_id, c.title, c.job_name, c.is_outlier) for c in clusters] == [+ (3, "Billing questions", "Support conversations", False),+ (-1, "Outliers", None, True),+ ]++ def test_a_viewer_without_cluster_access_gets_no_clusters(self) -> None:+ self.organization.available_product_features = [+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL}+ ]+ self.organization.save()+ AccessControl.objects.create(+ team=self.team,+ resource="ai_observability_clusters",+ access_level="none",+ organization_member=self.organization_membership,+ )+ bulk_create_events([self._run("00000000-0000-0000-0000-0000000c3004", [make_cluster(3, ["trace-1"])])])++ assert api.get_trace_clusters(self.team, self.user, "trace-1", T0).clusters == []++class TestTraceSummary(BaseTest):def setUp(self) -> None:super().setUp()diff --git a/products/ai_observability/backend/tests/test_trace_views.py b/products/ai_observability/backend/tests/test_trace_views.pyindex a19a03b8c271..f067ecd8ee5f 100644--- a/products/ai_observability/backend/tests/test_trace_views.py+++ b/products/ai_observability/backend/tests/test_trace_views.py@@ -26,7 +26,7 @@ from products.ai_observability.backend.logic.traces.summary_store import summaryfrom products.ai_observability.backend.models.review_queues import ReviewQueuefrom products.event_definitions.backend.models.property_definition import PropertyDefinition-from .logic.traces.rows import make_evaluation_result_event+from .logic.traces.rows import make_cluster, make_cluster_run_event, make_evaluation_result_eventT0 = datetime(2026, 9, 1, 10, 0, tzinfo=UTC)GENERATION = "00000000-0000-0000-0000-000000000001"@@ -199,6 +199,7 @@ class TestTraceViewSet(ClickhouseTestMixin, APIBaseTest):("trace", ""),("node", f"nodes/{_encode('trace-1')}/"),("evaluations", "evaluations/"),+ ("clusters", "clusters/?created_at=2026-09-01T10:00:00Z"),("search", "search/?q=invoice"),]]@@ -209,7 +210,8 @@ class TestTraceViewSet(ClickhouseTestMixin, APIBaseTest):_create_trace(self.team, "trace-1")headers = {}if with_api_key:- headers["authorization"] = f"Bearer {self.create_personal_api_key_with_scopes(['llm_analytics:read'])}"+ key = self.create_personal_api_key_with_scopes(["llm_analytics:read", "ai_observability_clusters:read"])+ headers["authorization"] = f"Bearer {key}"self.client.logout()def use(limiter: RateLimit, *args: object, **kwargs: object) -> ConcurrencySlot | None:@@ -344,6 +346,83 @@ class TestTraceEvaluationsView(ClickhouseTestMixin, APIBaseTest):assert (result["reasoning"], result["outcome"]) == (None, "pass")+class TestTraceClustersView(ClickhouseTestMixin, APIBaseTest):+ def _url(self, segment: str) -> str:+ return f"/api/projects/{self.team.id}/ai_observability/traces/{segment}/clusters/"++ def _create_cluster_run(self) -> None:+ bulk_create_events(+ [+ make_cluster_run_event(+ uuid="00000000-0000-0000-0000-0000000c4001",+ team=self.team,+ timestamp=T0 + timedelta(days=1),+ clusters=[+ make_cluster(3, ["trace-1"], title="Billing questions", description="Users ask about invoices.")+ ],+ )+ ]+ )++ def test_returns_the_clusters_in_camel_case(self) -> None:+ self._create_cluster_run()++ response = self.client.get(self._url(_encode("trace-1")), {"created_at": T0.isoformat()})++ assert response.status_code == 200+ assert response.json()["clusters"][0] | {"runAt": None} == {+ "runId": "1_trace_20260902_030000",+ "runAt": None,+ "jobId": None,+ "jobName": None,+ "clusterId": 3,+ "title": "Billing questions",+ "description": "Users ask about invoices.",+ "isOutlier": False,+ }++ @parameterized.expand(+ [+ ("an unencoded id", "trace-1", {"created_at": "2026-09-01T10:00:00Z"}),+ ("no created_at", _encode("trace-1"), {}),+ ("a malformed created_at", _encode("trace-1"), {"created_at": "yesterday"}),+ ("an out-of-range created_at", _encode("trace-1"), {"created_at": "9999-12-31T00:00:00Z"}),+ ]+ )+ def test_rejects_a_malformed_request(self, _name: str, segment: str, query: dict[str, str]) -> None:+ assert self.client.get(self._url(segment), query).status_code == 400++ def test_an_api_key_needs_the_clusters_scope(self) -> None:+ key = self.create_personal_api_key_with_scopes(["llm_analytics:read"])+ self.client.logout()++ response = self.client.get(+ self._url(_encode("trace-1")), {"created_at": T0.isoformat()}, headers={"authorization": f"Bearer {key}"}+ )++ assert response.status_code == 403++ def test_masks_clusters_the_viewer_may_not_read(self) -> None:+ self.organization.available_product_features = [+ {"key": AvailableFeature.PROPERTY_ACCESS_CONTROL, "name": AvailableFeature.PROPERTY_ACCESS_CONTROL}+ ]+ self.organization.save()+ definition = PropertyDefinition.objects.create(+ team=self.team, name="$ai_clusters", property_type="String", type=PropertyDefinition.Type.EVENT+ )+ PropertyAccessControl.objects.create(+ team=self.team,+ property_definition=definition,+ organization_member=self.organization_membership,+ access_level=PropertyAccessLevel.NONE.value,+ )+ self._create_cluster_run()++ response = self.client.get(self._url(_encode("trace-1")), {"created_at": T0.isoformat()})++ assert (response.status_code, response.json()) == (200, {"clusters": []})++def _create_feedback(team: Team) -> None:def event(uuid: str, name: str, properties: dict[str, object]) -> dict[str, object]:return {diff --git a/products/ai_observability/frontend/generated/api.schemas.ts b/products/ai_observability/frontend/generated/api.schemas.tsindex b37e5cec74b2..1355c1e2368a 100644--- a/products/ai_observability/frontend/generated/api.schemas.ts+++ b/products/ai_observability/frontend/generated/api.schemas.ts@@ -1431,6 +1431,27 @@ export interface TraceApi {git: TraceGitApi | null}+export interface TraceClusterApi {+ /** The clustering run that put the trace in this cluster. The cluster page is addressed by this id and the cluster id. */+ runId: string+ /** When the run finished. */+ runAt: string+ /** The clustering job the run belongs to, null for a run without a job. */+ jobId: string | null+ jobName: string | null+ /** The cluster's id within its run. -1 is the run's outliers. */+ clusterId: number+ title: string | null+ description: string | null+ /** The trace fit no cluster in this run. */+ isOutlier: boolean+}++export interface TraceClustersApi {+ /** The clusters that list the trace: for each clustering job, the newest scheduled run that lists it. Manual runs are left out. Clusters come before outliers, then newest first. */+ clusters: TraceClusterApi[]+}+export type TraceEvaluationResultOutcomeEnumApi =(typeof TraceEvaluationResultOutcomeEnumApi)[keyof typeof TraceEvaluationResultOutcomeEnumApi]@@ -5617,6 +5638,13 @@ export type AiObservabilityTracesRetrieveParams = {timestamp_hint?: string}+export type AiObservabilityTracesClustersRetrieveParams = {+ /**+ * When the trace started, as the trace resource's createdAt. Bounds which clustering runs are read.+ */+ created_at: string+}+export type AiObservabilityTracesFeedbackRetrieveParams = {/*** When the trace happened, as carried by links into it. Lets a trace older than the AI events retention load from the shared events table.diff --git a/products/ai_observability/frontend/generated/api.ts b/products/ai_observability/frontend/generated/api.tsindex 88c22d4a6f5b..e0c41c991663 100644--- a/products/ai_observability/frontend/generated/api.ts+++ b/products/ai_observability/frontend/generated/api.ts@@ -16,6 +16,7 @@ import type {AiObservabilityOfflineExperimentsResultCellsRetrieveParams,AiObservabilityOfflineExperimentsScorerSummariesListParams,AiObservabilityOfflineScorersHistoryListParams,+ AiObservabilityTracesClustersRetrieveParams,AiObservabilityTracesFeedbackRetrieveParams,AiObservabilityTracesNodesRetrieveParams,AiObservabilityTracesRetrieveParams,@@ -152,6 +153,7 @@ import type {TextReprRequestApi,TextReprResponseApi,TraceApi,+ TraceClustersApi,TraceEvaluationResultsApi,TraceFeedbackApi,TraceNodeDetailApi,@@ -689,6 +691,41 @@ export const aiObservabilityTracesRetrieve = async (})}+export const getAiObservabilityTracesClustersRetrieveUrl = (+ projectId: string,+ id: string,+ params: AiObservabilityTracesClustersRetrieveParams+) => {+ const normalizedParams = new URLSearchParams()++ Object.entries(params || {}).forEach(([key, value]) => {+ if (value !== undefined) {+ normalizedParams.append(key, value === null ? 'null' : String(value))+ }+ })++ const stringifiedParams = normalizedParams.toString()++ return stringifiedParams.length > 0+ ? `/api/projects/${projectId}/ai_observability/traces/${id}/clusters/?${stringifiedParams}`+ : `/api/projects/${projectId}/ai_observability/traces/${id}/clusters/`+}++/**+ * The clusters that list this trace, from the newest scheduled run of each clustering job that lists it.+ */+export const aiObservabilityTracesClustersRetrieve = async (+ projectId: string,+ id: string,+ params: AiObservabilityTracesClustersRetrieveParams,+ options?: RequestInit+): Promise<TraceClustersApi> => {+ return apiMutator<TraceClustersApi>(getAiObservabilityTracesClustersRetrieveUrl(projectId, id, params), {+ ...options,+ method: 'GET',+ })+}+export const getAiObservabilityTracesEvaluationsRetrieveUrl = (projectId: string, id: string) => {return `/api/projects/${projectId}/ai_observability/traces/${id}/evaluations/`}diff --git a/products/ai_observability/frontend/redesign/trace/TraceScene.tsx b/products/ai_observability/frontend/redesign/trace/TraceScene.tsxindex 8b3d04a75453..db07f62ecedc 100644--- a/products/ai_observability/frontend/redesign/trace/TraceScene.tsx+++ b/products/ai_observability/frontend/redesign/trace/TraceScene.tsx@@ -10,6 +10,7 @@ type ReadyValues = Pick<traceViewAdapterLogicValues,| 'header'| 'summary'+ | 'clustersChip'| 'mode'| 'tree'| 'selectedNodeId'@@ -63,6 +64,7 @@ function toReadyProps(values: ReadyValues, actions: ReadyActions): TraceViewReadheader: values.header,summary: {...values.summary,+ clusters: values.clustersChip,evals: values.evalsChip ? { chip: values.evalsChip, onClick: actions.showFailingEvals } : null,feedback: values.feedbackChip? { chip: values.feedbackChip, onClick: () => actions.showFeedback(null, 'chip') }@@ -125,6 +127,7 @@ export function TraceScene(): JSX.Element {backLink,header,summary,+ clustersChip,mode,tree,selectedNodeId,@@ -159,6 +162,7 @@ export function TraceScene(): JSX.Element {{header,summary,+ clustersChip,mode,tree,selectedNodeId,diff --git a/products/ai_observability/frontend/redesign/trace/adapter/testFixtures.ts b/products/ai_observability/frontend/redesign/trace/adapter/testFixtures.tsindex 1355a4147337..157602a99015 100644--- a/products/ai_observability/frontend/redesign/trace/adapter/testFixtures.ts+++ b/products/ai_observability/frontend/redesign/trace/adapter/testFixtures.ts@@ -2,6 +2,7 @@ import { LLMTrace, LLMTraceEvent } from '~/queries/schema/schema-general'import type {TraceApi,+ TraceClusterApi,TraceEvaluationResultApi,TraceEvaluationResultsApi,TraceFeedbackApi,@@ -146,6 +147,20 @@ export function makeEvaluationResult(overrides: Partial<TraceEvaluationResultApi}}+export function makeTraceCluster(overrides: Partial<TraceClusterApi> = {}): TraceClusterApi {+ return {+ runId: '1_trace_20260902_030000',+ runAt: '2026-09-02T03:40:00Z',+ jobId: '0192f2a4-5c1e-7000-8000-0000000c1a01',+ jobName: 'Support conversations',+ clusterId: 3,+ title: 'Billing questions',+ description: 'Users ask why an invoice changed.',+ isOutlier: false,+ ...overrides,+ }+}+export function makeFeedbackScore(overrides: Partial<TraceFeedbackScoreApi> = {}): TraceFeedbackScoreApi {return {id: 'score-1',diff --git a/products/ai_observability/frontend/redesign/trace/adapter/toClustersChip.test.ts b/products/ai_observability/frontend/redesign/trace/adapter/toClustersChip.test.tsnew file mode 100644index 000000000000..1f89381e6f33--- /dev/null+++ b/products/ai_observability/frontend/redesign/trace/adapter/toClustersChip.test.ts@@ -0,0 +1,42 @@+import { urls } from 'scenes/urls'++import { makeTraceCluster } from './testFixtures'+import { toClustersChip } from './toClustersChip'++describe('toClustersChip', () => {+ it.each([+ ['nothing loaded', null],+ ['no clusters', []],+ ])('shows no chip with %s', (_name, clusters) => {+ expect(toClustersChip(clusters)).toBeNull()+ })++ it('leads with the first cluster and links each cluster to its page', () => {+ const chip = toClustersChip([+ makeTraceCluster({+ runId: '1_trace_20260902_030000_job a',+ runAt: '2026-09-02T03:40:00Z',+ clusterId: 3,+ title: 'Billing questions',+ }),+ makeTraceCluster({+ runId: '1_trace_20260901_030000',+ clusterId: -1,+ title: null,+ jobName: null,+ isOutlier: true,+ }),+ makeTraceCluster({ runId: '1_trace_20260901_040000', clusterId: 7, title: null }),+ ])++ expect(chip?.first).toMatchObject({+ label: 'Billing questions',+ runAt: '2026-09-02T03:40:00Z',+ href: urls.aiObservabilityCluster('1_trace_20260902_030000_job a', 3),+ })+ expect(chip?.others.map(({ label, href }) => ({ label, href }))).toEqual([+ { label: 'Outliers', href: urls.aiObservabilityCluster('1_trace_20260901_030000', -1) },+ { label: 'Cluster 7', href: urls.aiObservabilityCluster('1_trace_20260901_040000', 7) },+ ])+ })+})diff --git a/products/ai_observability/frontend/redesign/trace/adapter/toClustersChip.ts b/products/ai_observability/frontend/redesign/trace/adapter/toClustersChip.tsnew file mode 100644index 000000000000..d2a4bf95d2ac--- /dev/null+++ b/products/ai_observability/frontend/redesign/trace/adapter/toClustersChip.ts@@ -0,0 +1,23 @@+import { urls } from 'scenes/urls'++import type { TraceClusterApi } from '../../../generated/api.schemas'+import { ClusterChipItem, TraceClustersChipProps } from '../components/TraceClustersChip'++function toItem(cluster: TraceClusterApi): ClusterChipItem {+ return {+ label: cluster.title ?? (cluster.isOutlier ? 'Outliers' : `Cluster ${cluster.clusterId}`),+ description: cluster.description,+ jobName: cluster.jobName,+ isOutlier: cluster.isOutlier,+ runAt: cluster.runAt,+ href: urls.aiObservabilityCluster(cluster.runId, cluster.clusterId),+ }+}++export function toClustersChip(clusters: TraceClusterApi[] | null): TraceClustersChipProps | null {+ if (!clusters?.length) {+ return null+ }+ const [first, ...others] = clusters.map(toItem)+ return { first, others }+}diff --git a/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx b/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsxindex 0b43644980e3..168f788e85f6 100644--- a/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx+++ b/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx@@ -10,6 +10,7 @@ import { performQuery } from '~/queries/query'import { initKeaTests } from '~/test/init'import { aiObservabilityTraceLogic } from '../../../aiObservabilityTraceLogic'+import type { TraceClusterApi } from '../../../generated/api.schemas'import { TraceScene } from '../TraceScene'import {decodeIdSegment,@@ -21,6 +22,7 @@ import {makeFeedbackText,makeNodeDetail,makeTrace,+ makeTraceCluster,makeTraceResource,} from './testFixtures'@@ -36,6 +38,7 @@ jest.mock('../../../utils', () => ({const TRACE_URL = '/api/projects/:team_id/ai_observability/traces/:id/'const NODE_URL = '/api/projects/:team_id/ai_observability/traces/:id/nodes/:node_id/'const EVALUATIONS_URL = '/api/projects/:team_id/ai_observability/traces/:id/evaluations/'+const CLUSTERS_URL = '/api/projects/:team_id/ai_observability/traces/:id/clusters/'const FEEDBACK_URL = '/api/projects/:team_id/ai_observability/traces/:id/feedback/'const DATASETS_URL = '/api/projects/:team_id/datasets/'const SEARCH_URL = '/api/projects/:team_id/ai_observability/traces/:id/search/'@@ -63,6 +66,8 @@ const nodeMock = {},}const evaluationsMock = { [EVALUATIONS_URL]: () => [200, makeEvaluationResults()] }+let clusters: TraceClusterApi[] = []+const clustersMock = { [CLUSTERS_URL]: () => [200, { clusters }] }const feedbackMock = { [FEEDBACK_URL]: () => [200, makeFeedback({ scores: [], responses: [] })] }const generation = makeEvent({@@ -93,6 +98,10 @@ function renderNewView(flags: Record<string, boolean> = {}): ReturnType<typeof r}describe('TraceScene', () => {+ beforeEach(() => {+ clusters = []+ })+afterEach(cleanup)describe('the new view', () => {@@ -104,6 +113,7 @@ describe('TraceScene', () => {[SEARCH_URL]: () => [200, { total: 1, matches: [{ nodeId: 'gen-1', count: 1 }] }],...nodeMock,...evaluationsMock,+ ...clustersMock,...feedbackMock,},})@@ -130,6 +140,19 @@ describe('TraceScene', () => {await waitFor(() => expect(nodeRequests).toContain('span-1'))})+ it('links the clusters chip to the cluster page', async () => {+ clusters = [+ makeTraceCluster({ runId: '1_trace_20260902_030000', clusterId: 3, title: 'Billing questions' }),+ ]+ const { findByText } = renderNewView()++ const chip = (await findByText('Billing questions')).closest('a')++ expect(+ chip?.getAttribute('href')?.endsWith(urls.aiObservabilityCluster('1_trace_20260902_030000', 3))+ ).toBe(true)+ })+it('searches from the header, fades the steps without a match and steps to the match in view', async () => {const { container, findAllByText, findByText } = renderNewView()const treeRow = async (name: string): Promise<Element> => {@@ -290,6 +313,7 @@ describe('TraceScene', () => {[TRACE_URL]: () => [200, makeTraceResource()],...nodeMock,...evaluationsMock,+ ...clustersMock,...feedbackMock,},})diff --git a/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.test.ts b/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.test.tsindex 290ba022d1bb..8b54310881c1 100644--- a/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.test.ts+++ b/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.test.ts@@ -3,6 +3,7 @@ import { decodeParams, router } from 'kea-router'import { expectLogic } from 'kea-test-utils'import posthog from 'posthog-js'+import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'import { urls } from 'scenes/urls'import { resumeKeaLoadersErrors, silenceKeaLoadersErrors } from '~/initKea'@@ -13,7 +14,14 @@ import { initKeaTests } from '~/test/init'import { aiObservabilityTraceLogic } from '../../../aiObservabilityTraceLogic'import type { TraceApi, TraceEvaluationResultsApi } from '../../../generated/api.schemas'import { traceSummaryLogic } from '../traceSummaryLogic'-import { decodeIdSegment, makeEvaluationResults, makeFeedback, makeNodeDetail, makeTraceResource } from './testFixtures'+import {+ decodeIdSegment,+ makeEvaluationResults,+ makeFeedback,+ makeNodeDetail,+ makeTraceCluster,+ makeTraceResource,+} from './testFixtures'import { traceViewAdapterLogic } from './traceViewAdapterLogic'jest.mock('~/queries/query', () => ({ ...jest.requireActual('~/queries/query'), performQuery: jest.fn() }))@@ -21,6 +29,8 @@ jest.mock('~/queries/query', () => ({ ...jest.requireActual('~/queries/query'),const TRACE_URL = '/api/projects/:team_id/ai_observability/traces/:id/'const NODE_URL = '/api/projects/:team_id/ai_observability/traces/:id/nodes/:node_id/'const EVALUATIONS_URL = '/api/projects/:team_id/ai_observability/traces/:id/evaluations/'+const CLUSTERS_URL = '/api/projects/:team_id/ai_observability/traces/:id/clusters/'+const CREATED_AT = '2026-09-01T10:15:00Z'const FEEDBACK_URL = '/api/projects/:team_id/ai_observability/traces/:id/feedback/'const SEARCH_URL = '/api/projects/:team_id/ai_observability/traces/:id/search/'const SUMMARY_URL = '/api/projects/:team_id/ai_observability/traces/:id/summary/'@@ -40,6 +50,8 @@ describe('traceViewAdapterLogic', () => {let traceGate: Promise<void>let nodeRequests: string[]let failingNodeId: string | null+ let clusterRequests: string[]+ let clustersStatus: numberlet feedbackStatus: numberlet searchStatus: numberlet summaryRequests: number@@ -56,6 +68,8 @@ describe('traceViewAdapterLogic', () => {traceGate = Promise.resolve()nodeRequests = []failingNodeId = null+ clusterRequests = []+ clustersStatus = 200feedbackStatus = 200searchStatus = 200summaryRequests = 0@@ -74,6 +88,12 @@ describe('traceViewAdapterLogic', () => {return [200, traceResource]},[EVALUATIONS_URL]: () => [200, evaluations],+ [CLUSTERS_URL]: ({ request }) => {+ clusterRequests.push(String(new URL(request.url).searchParams.get('created_at')))+ return clustersStatus === 200+ ? [200, { clusters: [makeTraceCluster()] }]+ : [clustersStatus, { detail: 'Server error.' }]+ },[FEEDBACK_URL]: () =>feedbackStatus === 200 ? [200, makeFeedback()] : [feedbackStatus, { detail: 'Server error.' }],[SEARCH_URL]: () =>@@ -156,6 +176,34 @@ describe('traceViewAdapterLogic', () => {])})+ it('asks for the clusters with the trace start once the trace arrives', async () => {+ let releaseTrace = (): void => {}+ traceGate = new Promise<void>((resolve) => {+ releaseTrace = resolve+ })+ mountAt()++ await waitFor(() => expect(nodeRequests).toEqual(['trace-1']))+ expect(clusterRequests).toEqual([])+ expect(logic.values.clustersChip).toBeNull()++ releaseTrace()+ await expectLogic(logic).toFinishAllListeners()++ expect(clusterRequests).toEqual([CREATED_AT])+ expect(logic.values.clustersChip?.first.label).toBe('Billing questions')+ })++ it('shows no clusters chip and no toast when the clusters read fails', async () => {+ const toast = jest.spyOn(lemonToast, 'error')+ clustersStatus = 500+ mountAt()++ await expectLogic(logic).toFinishAllListeners().toMatchValues({ status: 'ready', clustersChip: null })+ expect(clusterRequests).toEqual([CREATED_AT])+ expect(toast).not.toHaveBeenCalled()+ })+it('reports the reads that open the view as navigation and a click on an unread step as a selection', async () => {const capture = jest.spyOn(posthog, 'capture')traceResource = makeTraceResource({ defaultNodeId: 'gen-1' })diff --git a/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.ts b/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.tsindex a32ec75081bd..0a4b8c480a65 100644--- a/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.ts+++ b/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.ts@@ -14,6 +14,7 @@ import { aiObservabilityTraceLogic } from '../../../aiObservabilityTraceLogic'import type { SaveToDatasetButtonProps } from '../../../datasets/SaveToDatasetButton'import type {TraceApi,+ TraceClusterApi,TraceEvaluationResultsApi,TraceFeedbackApi,TraceNodeApi,@@ -21,9 +22,11 @@ import type {TraceTimelineRowApi,} from '../../../generated/api.schemas'import { GitBranchChipProps } from '../components/GitBranchChip'+import { TraceClustersChipProps } from '../components/TraceClustersChip'import { TraceHeaderProps } from '../components/TraceHeader'import type { TraceSearchBoxData } from '../components/TraceSearchBox'import { TraceSummaryBarProps } from '../components/TraceSummaryBar'+import { traceClustersLogic } from '../traceClustersLogic'import { traceFeedbackLogic } from '../traceFeedbackLogic'import { SEARCH_DEBOUNCE_MS, traceSearchLogic } from '../traceSearchLogic'import { traceSummaryLogic } from '../traceSummaryLogic'@@ -47,6 +50,7 @@ import {TraceSearchFailure,TraceSearchStatus,} from '../types'+import { toClustersChip } from './toClustersChip'import { toDatasetItemSource } from './toDatasetItemSource'import { firstFailingNodeId, toEvalOutcomesByNode, toEvalsChip } from './toEvalSummary'import { stepFeedbackOf, toFeedbackChip, toFeedbackMode, toStepFeedback } from './toFeedback'@@ -80,6 +84,7 @@ export interface traceViewAdapterLogicValues {featureFlags: FeatureFlagsSet // featureFlagLogicsearchParams: Record<string, any> // routercurrentTeamId: number | null // teamLogic+ clusters: TraceClusterApi[] | null // traceClustersLogictraceFeedback: TraceFeedbackApi | null // traceFeedbackLogictraceFeedbackFailed: boolean // traceFeedbackLogicquery: string // traceSearchLogic@@ -111,6 +116,7 @@ export interface traceViewAdapterLogicValues {tree: TraceNodeApi[] // traceViewLogicbackLink: LabeledLinkcanViewInThread: boolean+ clustersChip: TraceClustersChipProps | nulldatasetItemSource: SaveToDatasetButtonProps | nulldetailData: NodeDetailData | nulldetailTab: NodeDetailTab@@ -151,6 +157,7 @@ export interface traceViewAdapterLogicActions {setEventId: (eventId: string | null) => {eventId: string | null} // aiObservabilityTraceLogic+ loadClusters: (createdAt: string) => string // traceClustersLogicretryTraceFeedback: () => {value: true} // traceFeedbackLogic@@ -280,6 +287,7 @@ export interface traceViewAdapterLogicMeta {currentTeamId: number | null,traceId: string) => ConversationState+ clustersChip: (clusters: TraceClusterApi[] | null) => TraceClustersChipProps | nullevalsChip: (evaluationResults: TraceEvaluationResultsApi | null) => EvalsChipData | nullevalOutcomesByNode: (evaluationResults: TraceEvaluationResultsApi | null) => Record<string, EvalRollupOutcome>gitBranch: (trace: TraceApi | null) => GitBranchChipProps | null@@ -361,6 +369,8 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([['searchParams'],featureFlagLogic,['featureFlags'],+ traceClustersLogic({ traceId: props.traceId }),+ ['clusters'],traceFeedbackLogic({ traceId: props.traceId, timestampHint: props.timestampHint }),['traceFeedback', 'traceFeedbackFailed'],traceSearchLogic({ traceId: props.traceId, timestampHint: props.timestampHint }),@@ -375,6 +385,8 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([['setEventId', 'loadNeighbors'],traceViewLogic({ traceId: props.traceId, timestampHint: props.timestampHint }),['loadNode', 'loadTraceSuccess'],+ traceClustersLogic({ traceId: props.traceId }),+ ['loadClusters'],traceFeedbackLogic({ traceId: props.traceId, timestampHint: props.timestampHint }),['retryTraceFeedback'],traceSearchLogic({ traceId: props.traceId, timestampHint: props.timestampHint }),@@ -552,6 +564,10 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([return toThread({ traceId, createdAt, load, teamId })},],+ clustersChip: [+ (s) => [s.clusters],+ (clusters: TraceClusterApi[] | null): TraceClustersChipProps | null => toClustersChip(clusters),+ ],evalsChip: [(s) => [s.evaluationResults],(evaluationResults: TraceEvaluationResultsApi | null): EvalsChipData | null =>@@ -690,6 +706,7 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([},loadTraceSuccess: ({ trace }) => {actions.loadNeighbors(props.traceId, trace.createdAt)+ actions.loadClusters(trace.createdAt)// Cluster and session pages link to a trace with tab=summary. The mode opens without generating.// A link that also names a step opens that step, because the Summary mode covers the whole trace.if (values.initialTab === 'summary' && values.mode !== 'summary' && !values.eventId) {diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceClustersChip.stories.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceClustersChip.stories.tsxnew file mode 100644index 000000000000..eed5c1ce4ca7--- /dev/null+++ b/products/ai_observability/frontend/redesign/trace/components/TraceClustersChip.stories.tsx@@ -0,0 +1,26 @@+import type { Meta, StoryObj } from '@storybook/react'++import { FIXTURE_CLUSTER, FIXTURE_CLUSTERS_CHIP, FIXTURE_OUTLIER_CLUSTER, withWidth } from '../storyFixtures'+import { TraceClustersChip } from './TraceClustersChip'++const meta: Meta<typeof TraceClustersChip> = {+ title: 'Scenes-App/AI observability/Trace view/Trace clusters chip',+ component: TraceClustersChip,+ args: { first: FIXTURE_CLUSTER, others: [] },+}+export default meta++type Story = StoryObj<typeof TraceClustersChip>++export const OneCluster: Story = {}+export const OutlierOnly: Story = { args: { first: FIXTURE_OUTLIER_CLUSTER } }+export const LongTitleNarrow: Story = {+ args: {+ ...FIXTURE_CLUSTERS_CHIP,+ first: {+ ...FIXTURE_CLUSTER,+ label: 'Users who ask to restore an archived project after the retention window has passed',+ },+ },+ decorators: [withWidth(240)],+}diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceClustersChip.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceClustersChip.tsxnew file mode 100644index 000000000000..d4e101a4e78e--- /dev/null+++ b/products/ai_observability/frontend/redesign/trace/components/TraceClustersChip.tsx@@ -0,0 +1,81 @@+import { LemonButton, LemonMenu, LemonTag, Link, Tooltip } from '@posthog/lemon-ui'++import { dayjs } from 'lib/dayjs'++export interface ClusterChipItem {+ label: string+ description: string | null+ jobName: string | null+ isOutlier: boolean+ runAt: string+ href: string+}++export interface TraceClustersChipProps {+ first: ClusterChipItem+ others: ClusterChipItem[]+}++function ClusterTooltip({ item }: { item: ClusterChipItem }): JSX.Element {+ return (+ <div className="flex max-w-80 flex-col gap-1">+ <span className="font-semibold">{item.label}</span>+ {item.description ? <span>{item.description}</span> : null}+ {item.isOutlier ? <span>This trace didn't fit any cluster in this run.</span> : null}+ {item.jobName ? <span className="opacity-75">From {item.jobName}</span> : null}+ <span className="opacity-75">Run {dayjs(item.runAt).fromNow()}</span>+ </div>+ )+}++export function TraceClustersChip({ first, others }: TraceClustersChipProps): JSX.Element {+ return (+ <span className="inline-flex max-w-full min-w-0 items-center gap-1">+ <Tooltip title={<ClusterTooltip item={first} />}>+ <Link to={first.href} subtle className="min-w-0" data-attr="trace-view-cluster-chip">+ <LemonTag weight="normal" type={first.isOutlier ? 'caution' : 'default'} className="max-w-full">+ <span className="shrink-0">Cluster: </span>+ <span className="max-w-60 truncate">{first.label}</span>+ </LemonTag>+ </Link>+ </Tooltip>+ {others.length > 0 ? (+ <LemonMenu+ items={[+ {+ title: 'Also in',+ items: others.map((item) => ({+ label: (+ <span className="flex min-w-0 flex-col">+ <span className="flex items-center gap-1">+ <span className="truncate">{item.label}</span>+ {item.isOutlier ? (+ <LemonTag size="small" type="caution">+ Outlier+ </LemonTag>+ ) : null}+ </span>+ {item.jobName ? (+ <span className="text-xs text-secondary">{item.jobName}</span>+ ) : null}+ </span>+ ),+ to: item.href,+ 'data-attr': 'trace-view-cluster-chip-item',+ })),+ },+ ]}+ >+ <LemonButton+ size="xsmall"+ type="secondary"+ aria-label={`${others.length} more ${others.length === 1 ? 'cluster' : 'clusters'}`}+ data-attr="trace-view-cluster-chip-more"+ >+ {`+${others.length}`}+ </LemonButton>+ </LemonMenu>+ ) : null}+ </span>+ )+}diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceSummaryBar.stories.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceSummaryBar.stories.tsxindex 5eca7bb94ffc..a4c1f409af74 100644--- a/products/ai_observability/frontend/redesign/trace/components/TraceSummaryBar.stories.tsx+++ b/products/ai_observability/frontend/redesign/trace/components/TraceSummaryBar.stories.tsx@@ -1,6 +1,6 @@import type { Meta, StoryObj } from '@storybook/react'-import { FIXTURE_STATS, withWidth } from '../storyFixtures'+import { FIXTURE_CLUSTERS_CHIP, FIXTURE_STATS, withWidth } from '../storyFixtures'import { TraceSummaryBar } from './TraceSummaryBar'const meta: Meta<typeof TraceSummaryBar> = {@@ -11,6 +11,7 @@ const meta: Meta<typeof TraceSummaryBar> = {timestamp: '2026-09-01T10:15:00Z',person: { label: '[email protected]', href: '/person/ana' },totals: FIXTURE_STATS,+ clusters: null,},}export default meta@@ -24,7 +25,8 @@ export const Default: Story = wideexport const Anonymous: Story = { ...wide, args: { person: null } }export const ShortId: Story = { ...wide, args: { traceId: 'notes-run-42' } }export const LongSlugId: Story = { ...wide, args: { traceId: 'support-chat-session-2026-09-01-weekly-billing-review' } }-export const Narrow: Story = { decorators: [withWidth(420)] }+export const WithClusters: Story = { ...wide, args: { clusters: FIXTURE_CLUSTERS_CHIP } }+export const Narrow: Story = { args: { clusters: FIXTURE_CLUSTERS_CHIP }, decorators: [withWidth(420)] }export const WithFeedback: Story = {args: { feedback: { chip: { total: 6 }, onClick: () => {} } },decorators: [withWidth(420)],diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceSummaryBar.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceSummaryBar.tsxindex 7d1077f20e9d..68196404b4e5 100644--- a/products/ai_observability/frontend/redesign/trace/components/TraceSummaryBar.tsx+++ b/products/ai_observability/frontend/redesign/trace/components/TraceSummaryBar.tsx@@ -9,6 +9,7 @@ import { FeedbackChip, FeedbackChipProps } from './FeedbackChip'import { GitBranchChip, GitBranchChipProps } from './GitBranchChip'import { NodeStatsLine } from './NodeStatsLine'import { PersonChip } from './PersonChip'+import { TraceClustersChip, TraceClustersChipProps } from './TraceClustersChip'import { TraceIdChip } from './TraceIdChip'export interface TraceSummaryBarProps {@@ -16,6 +17,7 @@ export interface TraceSummaryBarProps {timestamp: stringperson: LabeledLink | nulltotals: TraceNodeStatsApi+ clusters?: TraceClustersChipProps | nullevals?: EvalsChipProps | nullfeedback?: FeedbackChipProps | nullgit?: GitBranchChipProps | null@@ -26,6 +28,7 @@ export function TraceSummaryBar({timestamp,person,totals,+ clusters = null,evals = null,feedback = null,git = null,@@ -44,6 +47,7 @@ export function TraceSummaryBar({/></LemonTag>{person ? <PersonChip person={person} /> : null}+ {clusters ? <TraceClustersChip {...clusters} /> : null}{evals ? <EvalsChip {...evals} /> : null}{feedback ? <FeedbackChip {...feedback} /> : null}{git ? <GitBranchChip {...git} /> : null}diff --git a/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx b/products/ai_observability/frontend/redesign/trace/storyFixtures.tsxindex 11b7a6f57379..147d6c39149b 100644--- a/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx+++ b/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx@@ -7,6 +7,7 @@ import type {TraceSummaryContentApi,TraceTimelineRowApi,} from '../../generated/api.schemas'+import type { ClusterChipItem, TraceClustersChipProps } from './components/TraceClustersChip'import { SampleNodeDetail, SampleTraceFixture } from './sampleFixtures/sampleTraceFixture'import {ConversationTurn,@@ -485,3 +486,36 @@ export function withWidth(px: number): Decorator {</div>)}++export const FIXTURE_CLUSTER: ClusterChipItem = {+ label: 'Billing questions',+ description: 'Users ask why an invoice changed after adding seats.',+ jobName: 'Support conversations',+ isOutlier: false,+ runAt: '2026-09-02T03:40:00Z',+ href: '/ai-observability/clusters/1_trace_20260902_030000/3',+}++export const FIXTURE_OUTLIER_CLUSTER: ClusterChipItem = {+ label: 'Outliers',+ description: null,+ jobName: 'Agent runs',+ isOutlier: true,+ runAt: '2026-09-01T03:40:00Z',+ href: '/ai-observability/clusters/1_trace_20260901_030000/-1',+}++export const FIXTURE_CLUSTERS_CHIP: TraceClustersChipProps = {+ first: FIXTURE_CLUSTER,+ others: [+ FIXTURE_OUTLIER_CLUSTER,+ {+ label: 'Refund requests',+ description: 'Users ask for money back on an annual plan.',+ jobName: null,+ isOutlier: false,+ runAt: '2026-09-02T04:40:00Z',+ href: '/ai-observability/clusters/1_trace_20260902_040000/5',+ },+ ],+}diff --git a/products/ai_observability/frontend/redesign/trace/traceClustersLogic.ts b/products/ai_observability/frontend/redesign/trace/traceClustersLogic.tsnew file mode 100644index 000000000000..a286de9cfcea--- /dev/null+++ b/products/ai_observability/frontend/redesign/trace/traceClustersLogic.ts@@ -0,0 +1,71 @@+import { MakeLogicType, kea, key, path, props } from 'kea'+import { loaders } from 'kea-loaders'++import { ApiConfig } from 'lib/api'++import { aiObservabilityTracesClustersRetrieve } from '../../generated/api'+import type { TraceClusterApi } from '../../generated/api.schemas'+import { encodeTraceIdSegment } from './traceIdSegment'++export interface TraceClustersLogicProps {+ traceId: string+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface traceClustersLogicValues {+ clusters: TraceClusterApi[] | null+ clustersLoading: boolean+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface traceClustersLogicActions {+ loadClusters: (createdAt: string) => string+ loadClustersFailure: (+ error: string,+ errorObject?: any+ ) => {+ error: string+ errorObject?: any+ }+ loadClustersSuccess: (+ clusters: TraceClusterApi[],+ payload?: string+ ) => {+ clusters: TraceClusterApi[]+ payload?: string+ }+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface traceClustersLogicMeta {+ key: string+}++export type traceClustersLogicType = MakeLogicType<+ traceClustersLogicValues,+ traceClustersLogicActions,+ TraceClustersLogicProps,+ traceClustersLogicMeta+>++export const traceClustersLogic = kea<traceClustersLogicType>([+ props({} as TraceClustersLogicProps),+ key((props) => props.traceId),+ path((key) => ['products', 'ai_observability', 'frontend', 'redesign', 'trace', 'traceClustersLogic', key]),+ loaders(({ props }) => ({+ clusters: [+ null as TraceClusterApi[] | null,+ {+ // The read is bounded by the trace's start, so it waits for the trace instead of starting on mount.+ loadClusters: async (createdAt: string): Promise<TraceClusterApi[]> => {+ const { clusters } = await aiObservabilityTracesClustersRetrieve(+ String(ApiConfig.getCurrentProjectId()),+ encodeTraceIdSegment(props.traceId),+ { created_at: createdAt }+ )+ return clusters+ },+ },+ ],+ })),+])diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex cff07bc9a875..f535c018cadc 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -121554,6 +121554,27 @@ export namespace Schemas {git: TraceGit | null;}+ export interface TraceCluster {+ /** The clustering run that put the trace in this cluster. The cluster page is addressed by this id and the cluster id. */+ runId: string;+ /** When the run finished. */+ runAt: string;+ /** The clustering job the run belongs to, null for a run without a job. */+ jobId: string | null;+ jobName: string | null;+ /** The cluster's id within its run. -1 is the run's outliers. */+ clusterId: number;+ title: string | null;+ description: string | null;+ /** The trace fit no cluster in this run. */+ isOutlier: boolean;+ }++ export interface TraceClusters {+ /** The clusters that list the trace: for each clustering job, the newest scheduled run that lists it. Manual runs are left out. Clusters come before outliers, then newest first. */+ clusters: TraceCluster[];+ }+export type TraceEvaluationResultOutcomeEnum = typeof TraceEvaluationResultOutcomeEnum[keyof typeof TraceEvaluationResultOutcomeEnum];@@ -130170,6 +130191,13 @@ export namespace Schemas {timestamp_hint?: string;};+ export type AiObservabilityTracesClustersRetrieveParams = {+ /**+ * When the trace started, as the trace resource's createdAt. Bounds which clustering runs are read.+ */+ created_at: string;+ };+export type AiObservabilityTracesFeedbackRetrieveParams = {/*** When the trace happened, as carried by links into it. Lets a trace older than the AI events retention load from the shared events table.