Skip to content

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

feat(aio): trace clusters chip (#124360)

Carlos Marchal0212673ed017
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index 85feaaf0c871..a5c0ce1e5885 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -9734,6 +9734,18 @@ snapshots:
hash: v1.k794b7964.909ba48aa0b1f664036a5f22fad341be78fc8c1a058a8117ed2e3c870c18a7c3.foFLxGwVGgGhafMdp8x2w6_GQp8BBEed6O5W5zizT0A
scenes-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_Me0S92srt0iYGNFFvnczxucni9d4GiK01rY
scenes-app-ai-observability-trace-view-trace-header--default--dark:
hash: v1.k794b7964.89f74988daa805a5decedf40f47256dc0776cf10499f7927bccec49753e659b8.BAtU5Cxiu3j-JRB9Z_iy032Q7TVs-L0M01FCCizn3n0
scenes-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-pTHV3UHv9PnQ
scenes-app-ai-observability-trace-view-trace-summary-bar--narrow--dark:
- hash: v1.k794b7964.daebccd14686a4ffa02937c8621dc74845153b053e2c5581ac18055fc85c2011.Jwh3UjTBshXuWKYsYsjgLLcwNkROjdAxPLk5xY7oQys
+ hash: v1.k794b7964.ee5d03658549f32a225e94021f63169560c9c5e360f6deae750a621efadfcedc.zL6G2ExwgKkeQVCD9aAuseAfHRQxOnodZkXVt0huPRw
scenes-app-ai-observability-trace-view-trace-summary-bar--narrow--light:
- hash: v1.k794b7964.89c5f822021e4c9c6581b1867d29be28fa87cf638297617fe1dd9f46c87310df.mx9UHOPdDLvPVcF_QQQRTgNGytxi_bTrB_AJBimtWjQ
+ hash: v1.k794b7964.acb3645733c46cf841a3da15259dbee824c6046b7c6db42bf451a4ca992340eb.C6XyBCxowGHCRIqzsNYsziyhPPdXoTh9xlpfEzrq67I
scenes-app-ai-observability-trace-view-trace-summary-bar--narrow-with-long-git-branch--dark:
hash: v1.k794b7964.306fabde159267a2ffad36e356b4db293663b87a2ca8bf9c53575230fe4ccd41.-1ojgmfWHNK7Mv4-rNw_HlYOul55PvTX7utdFjsqDFs
scenes-app-ai-observability-trace-view-trace-summary-bar--narrow-with-long-git-branch--light:
@@ -9818,6 +9830,10 @@ snapshots:
hash: v1.k794b7964.b0dd60321acfc66eff4b4fe61c0123016d6ef51e83d18e1a33989d71056cf4c4.rhGXCqb0ZHRrzjcvMjSYO0_vKIrG0vZRA9yacMU9g4A
scenes-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_tJ2A
scenes-app-ai-observability-trace-view-trace-summary-bar--with-feedback--dark:
hash: v1.k794b7964.4ee4b41df55c5bc9f386036bb5c7bf684ca90215cb9046f62375c4d8eb2defd4.Xu2hxbSf7Oc5ztiyAnhnTkeZCdhT-YnBK5mMKOAfG8E
scenes-app-ai-observability-trace-view-trace-summary-bar--with-feedback--light:
diff --git a/frontend/src/initKea.ts b/frontend/src/initKea.ts
index 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 chip
loadTraceFeedback: 'products.ai_observability.frontend.redesign.trace.traceFeedbackLogic', // The trace view's Feedback mode shows the error
loadSearchResults: 'products.ai_observability.frontend.redesign.trace.traceSearchLogic', // The trace view's search box shows the error
// The trace view's Summary mode shows the error
diff --git a/products/ai_observability/backend/facade/api.py b/products/ai_observability/backend/facade/api.py
index 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_runs
from ..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, TraceCluster
from ..logic.traces.evaluation_result import EvaluationResult
from ..logic.traces.evaluation_result_queries import load_evaluation_results, load_output_configs
from ..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.py
index 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: str
name: str | None
diff --git a/products/ai_observability/backend/logic/traces/cluster_queries.py b/products/ai_observability/backend/logic/traces/cluster_queries.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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, timedelta
from typing import Any
from posthog.models import Team
+from products.ai_observability.backend.logic.traces.cluster_queries import ClusterRunRow
from products.ai_observability.backend.logic.traces.evaluation_result_queries import EvaluationResultRow
from 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 LoadedT
from products.ai_observability.backend.models.evaluations import Evaluation
from 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_property
T0 = 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.py
index 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 summary
from products.ai_observability.backend.models.review_queues import ReviewQueue
from 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_event
T0 = 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.ts
index 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.ts
index 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.tsx
index 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): TraceViewRead
header: 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
index 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: number
let feedbackStatus: number
let searchStatus: number
let summaryRequests: number
@@ -56,6 +68,8 @@ describe('traceViewAdapterLogic', () => {
traceGate = Promise.resolve()
nodeRequests = []
failingNodeId = null
+ clusterRequests = []
+ clustersStatus = 200
feedbackStatus = 200
searchStatus = 200
summaryRequests = 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.ts
index 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 // featureFlagLogic
searchParams: Record<string, any> // router
currentTeamId: number | null // teamLogic
+ clusters: TraceClusterApi[] | null // traceClustersLogic
traceFeedback: TraceFeedbackApi | null // traceFeedbackLogic
traceFeedbackFailed: boolean // traceFeedbackLogic
query: string // traceSearchLogic
@@ -111,6 +116,7 @@ export interface traceViewAdapterLogicValues {
tree: TraceNodeApi[] // traceViewLogic
backLink: LabeledLink
canViewInThread: boolean
+ clustersChip: TraceClustersChipProps | null
datasetItemSource: SaveToDatasetButtonProps | null
detailData: NodeDetailData | null
detailTab: NodeDetailTab
@@ -151,6 +157,7 @@ export interface traceViewAdapterLogicActions {
setEventId: (eventId: string | null) => {
eventId: string | null
} // aiObservabilityTraceLogic
+ loadClusters: (createdAt: string) => string // traceClustersLogic
retryTraceFeedback: () => {
value: true
} // traceFeedbackLogic
@@ -280,6 +287,7 @@ export interface traceViewAdapterLogicMeta {
currentTeamId: number | null,
traceId: string
) => ConversationState
+ clustersChip: (clusters: TraceClusterApi[] | null) => TraceClustersChipProps | null
evalsChip: (evaluationResults: TraceEvaluationResultsApi | null) => EvalsChipData | null
evalOutcomesByNode: (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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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:&nbsp;</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.tsx
index 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 = wide
export 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.tsx
index 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: string
person: LabeledLink | null
totals: TraceNodeStatsApi
+ clusters?: TraceClustersChipProps | null
evals?: EvalsChipProps | null
feedback?: FeedbackChipProps | null
git?: 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.tsx
index 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.ts
new file mode 100644
index 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.ts
index 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.