: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): open stateless traces on the user-visible generation (#123530)
Carlos Marchalc77538825cc8
diff --git a/posthog/hogql/ACCESS_CONTROL.md b/posthog/hogql/ACCESS_CONTROL.mdindex d22be43db44a..d597c5875249 100644--- a/posthog/hogql/ACCESS_CONTROL.md+++ b/posthog/hogql/ACCESS_CONTROL.md@@ -233,6 +233,7 @@ Several catalog tables expose such columns because reading them scans far less dThe mapping is keyed by the stored column name, not the HogQL field name, so an expression field that reads a mirror column masks too: `flag_evaluations.response` reads the stored `response` column through `nullIf`, and the hidden `flag_evaluation_response` reads it bare, and both mask. The hidden `goe_N.key` on `flag_evaluations` reads the stored `$group_N` column through an expression field, and it masks too.For AI columns, `AI_PROPERTY_TO_COLUMN` in `posthog/hogql/database/schema/ai_events.py` is shared with the query rewriter.One rule for `$ai_input` masks both `events.properties.$ai_input` and `ai_events.input`, including nested reads such as `input[1].content`.+The hidden length fields `input_state_length` and `output_state_length` follow the rule of their state property, so a masked state also hides whether it exists.The same rule applies when a filter or an aggregate reads the column.Nested keys in an allowed AI payload are not separate event properties: a restriction on the event property `content` does not restrict `input.content`.That resolver rewrites a restricted mirror column to the same `Constant(value=None, type=StringType(nullable=True))` the source property lowers to, before the AST reaches the printer — so the mirror column and its source property are one AST node by the time comparisons and nullability are decided, not two independently masked spellings that could drift apart.diff --git a/posthog/hogql/database/schema/ai_events.py b/posthog/hogql/database/schema/ai_events.pyindex 991d472e8b98..4415f433271e 100644--- a/posthog/hogql/database/schema/ai_events.py+++ b/posthog/hogql/database/schema/ai_events.py@@ -74,6 +74,13 @@ AI_PROPERTY_TO_COLUMN: dict[str, str] = {"$ai_tools": "tools",}+# A string column stores its lengths as a subcolumn of their own, so a length check skips the content.+# A rule on the source column's property masks the subcolumn too (see restricted_properties.py).+AI_SUBCOLUMN_TO_SOURCE: dict[str, str] = {+ "input_state.size": "input_state",+ "output_state.size": "output_state",+}+class AiEventsTable(Table):description: str = "AI observability events ($ai_generation, $ai_span, $ai_trace, $ai_evaluation, etc.) capturing model calls, token usage, costs, and trace structure."@@ -253,6 +260,18 @@ class AiEventsTable(Table):"tools": StringJSONDatabaseField(name="tools", nullable=True, description="JSON of the tool/function definitions available to the model."),+ "input_state_length": IntegerDatabaseField(+ name="input_state.size",+ nullable=True,+ hidden=True,+ description="Length in bytes of the input state JSON, read without loading the state itself.",+ ),+ "output_state_length": IntegerDatabaseField(+ name="output_state.size",+ nullable=True,+ hidden=True,+ description="Length in bytes of the output state JSON, read without loading the state itself.",+ ),# Person join via person_distinct_ids"pdi": LazyJoin(from_field=["distinct_id"],diff --git a/posthog/hogql/printer/test/test_property_access_control.py b/posthog/hogql/printer/test/test_property_access_control.pyindex 935800d0f1bc..f1b5d3cf2eaf 100644--- a/posthog/hogql/printer/test/test_property_access_control.py+++ b/posthog/hogql/printer/test/test_property_access_control.py@@ -396,10 +396,11 @@ class TestRestrictPropertiesInHogQL(BaseTest):("tokens", "$ai_input_tokens", "a.input_tokens"),("cost", "$ai_total_cost_usd", "a.total_cost_usd"),("error", "$ai_is_error", "a.is_error"),+ ("state length", "$ai_input_state", "a.input_state_length", "input_state.size"),])def test_ai_column_and_nested_reads_use_the_canonical_property_rule(- self, _name: str, property_name: str, expression: str+ self, _name: str, property_name: str, expression: str, printed_column: str | None = None) -> None:self.event_prop.name = property_nameself.event_prop.save()@@ -415,7 +416,7 @@ class TestRestrictPropertiesInHogQL(BaseTest):assert "NULL AS restricted_value" in sqlassert "JSONExtract" not in sql- assert expression.split("[")[0] not in sql+ assert (printed_column or expression.split("[")[0]) not in sqldef test_ai_json_content_is_not_an_event_property(self) -> None:PropertyAccessControl.objects.create(diff --git a/posthog/hogql/restricted_properties.py b/posthog/hogql/restricted_properties.pyindex f3e6a38d4531..4c119ff0f1a6 100644--- a/posthog/hogql/restricted_properties.py+++ b/posthog/hogql/restricted_properties.py@@ -6,7 +6,7 @@ from posthog.hogql import astfrom posthog.hogql.constants import FEATURE_FLAG_PROPERTY_PREFIXfrom posthog.hogql.context import HogQLContextfrom posthog.hogql.database.postgres_table import PostgresTable-from posthog.hogql.database.schema.ai_events import AI_PROPERTY_TO_COLUMN, AiEventsTable+from posthog.hogql.database.schema.ai_events import AI_PROPERTY_TO_COLUMN, AI_SUBCOLUMN_TO_SOURCE, AiEventsTablefrom posthog.hogql.database.schema.events import EventsGroupSubTable, EventsPersonSubTable, EventsTablefrom posthog.hogql.database.schema.flag_evaluations import FlagEvaluationsPersonSubTable, FlagEvaluationsTablefrom posthog.hogql.database.schema.groups import GroupsTable, RawGroupsTable@@ -49,6 +49,9 @@ _FLAG_EVALUATIONS_MIRRORED_COLUMNS: dict[str, str] = {_AI_EVENTS_MIRRORED_COLUMNS = {column: property_name for property_name, column in AI_PROPERTY_TO_COLUMN.items()}+_AI_EVENTS_MIRRORED_COLUMNS |= {+ subcolumn: _AI_EVENTS_MIRRORED_COLUMNS[source] for subcolumn, source in AI_SUBCOLUMN_TO_SOURCE.items()+}def mirrored_property_for_column(table_type: ast.Type, column_name: str, context: HogQLContext) -> str | None:diff --git a/products/ai_observability/backend/logic/traces/trace.py b/products/ai_observability/backend/logic/traces/trace.pyindex 33a59104b7d9..442654ffd219 100644--- a/products/ai_observability/backend/logic/traces/trace.py+++ b/products/ai_observability/backend/logic/traces/trace.py@@ -70,11 +70,9 @@ class Trace:@cached_propertydef default_node_id(self) -> str:- if any(event.is_trace_event for event in self.events):+ if any(event.is_trace_event and event.row.has_state for event in self.events):return self.id- first_generation = next((node for node in self.tree if node.event.kind == "generation"), None)- chosen = first_generation or next(iter(self.tree), None)- return chosen.event.id if chosen else self.id+ return next(iter(self.thread_node_ids), None) or next((node.event.id for node in self.tree), self.id)@cached_propertydef node_ids_by_alias(self) -> dict[str, str]:diff --git a/products/ai_observability/backend/logic/traces/trace_queries.py b/products/ai_observability/backend/logic/traces/trace_queries.pyindex 594a7174a512..72461ae117f9 100644--- a/products/ai_observability/backend/logic/traces/trace_queries.py+++ b/products/ai_observability/backend/logic/traces/trace_queries.py@@ -1,6 +1,6 @@import jsonimport math-from collections.abc import Callable, Sequence+from collections.abc import Callable, Iterable, Sequencefrom dataclasses import replacefrom datetime import datetimefrom functools import reduce@@ -63,6 +63,7 @@ class TraceEventRow:latency: float | Noneis_error: boolerror_is_truthy: bool+ has_state: boolingestion_source: str | Nonegit_branch: str | Nonegit_repo: str | None@@ -148,6 +149,7 @@ _SELECTED: dict[str, ast.Expr] = {# The native error column extracts $ai_error as a string, which loses the JSON type that decides truthiness."error_raw": _raw_property("$ai_error"),"ingestion_source": ast.Field(chain=["properties", "$ai_ingestion_source"]),+ "has_state": ast.Placeholder(expr=ast.Field(chain=["has_state"])),"git_branch": ast.Field(chain=["properties", "$ai_git_branch"]),"git_repo": ast.Field(chain=["properties", "$ai_git_repo"]),}@@ -253,6 +255,30 @@ def _person_query(distinct_id: str) -> ast.SelectQuery:)+# SDKs send an empty state as `null`, `""` or `{}`, so a state of at most 4 bytes holds nothing to show.+_EMPTY_STATE_MAX_BYTES = 4+++def _has_state(lengths: Iterable[ast.Expr]) -> ast.Expr:+ return ast.Or(+ exprs=[+ ast.CompareOperation(+ op=ast.CompareOperationOp.Gt, left=length, right=ast.Constant(value=_EMPTY_STATE_MAX_BYTES)+ )+ for length in lengths+ ]+ )+++# ClickHouse reads the whole state column for any function of `input_state`, so ai_events checks the length+# subcolumns, which load no state content.+_AI_EVENTS_HAS_STATE = _has_state((ast.Field(chain=["input_state_length"]), ast.Field(chain=["output_state_length"])))+# The events fallback reads the state from the properties JSON, where a missing key is an empty string.+_EVENTS_HAS_STATE = _has_state(+ tuple(ast.Call(name="length", args=[ast.Field(chain=[column])]) for column in ("input_state", "output_state"))+)++def _trace_filter(trace_id: str) -> ast.Expr:return _equals("trace_id", trace_id)@@ -272,7 +298,7 @@ def _read(tag_queries(name=name)response = query_ai_events(query=query,- placeholders={"filter_conditions": _trace_filter(trace_id)},+ placeholders={"filter_conditions": _trace_filter(trace_id), "has_state": _AI_EVENTS_HAS_STATE},team=team,user=user,query_type=name,@@ -280,7 +306,8 @@ def _read(fallback_placeholders={"filter_conditions": events_filter(trace_filter=_trace_filter(trace_id), event_filter=_event_in(event_names), window=window- )+ ),+ "has_state": _EVENTS_HAS_STATE,},posthog_tables_only=True,settings=settings,@@ -360,6 +387,7 @@ def _trace_event_row(values: Sequence[Any]) -> TraceEventRow:latency=read_number(raw["latency"]),is_error=read_flag(raw["is_error"]),error_is_truthy=is_truthy_json(raw["error_raw"]),+ has_state=read_flag(raw["has_state"]),ingestion_source=read_text(raw["ingestion_source"]),git_branch=read_text(raw["git_branch"]),git_repo=read_text(raw["git_repo"]),diff --git a/products/ai_observability/backend/tests/logic/traces/rows.py b/products/ai_observability/backend/tests/logic/traces/rows.pyindex 948bf84916be..7fa5f3d79cb7 100644--- a/products/ai_observability/backend/tests/logic/traces/rows.py+++ b/products/ai_observability/backend/tests/logic/traces/rows.py@@ -35,6 +35,7 @@ def make_row(**overrides: Any) -> TraceEventRow:"latency": None,"is_error": False,"error_is_truthy": False,+ "has_state": False,"ingestion_source": None,"git_branch": None,"git_repo": None,diff --git a/products/ai_observability/backend/tests/logic/traces/test_trace.py b/products/ai_observability/backend/tests/logic/traces/test_trace.pyindex 88402b9d6103..f0f7e669806b 100644--- a/products/ai_observability/backend/tests/logic/traces/test_trace.py+++ b/products/ai_observability/backend/tests/logic/traces/test_trace.py@@ -94,24 +94,38 @@ def test_person_label(_name: str, person: PersonRow | None, expected: str | None@parameterized.expand([(- "a trace event makes the root the default",- [{"event": "$ai_trace"}, {"event": "$ai_generation"}],+ "a trace event with state makes the root the default",+ [{"event": "$ai_trace", "has_state": True}, {"event": "$ai_generation"}],"trace-1",),(- "otherwise the first top-level generation",+ "a trace event without state gives way to the user-visible generation",[- {"event": "$ai_span", "timestamp": T0},+ {"event": "$ai_trace", "timestamp": T0},{"event": "$ai_generation", "timestamp": T0 + timedelta(seconds=1)},{"event": "$ai_generation", "timestamp": T0 + timedelta(seconds=2)},],+ "e2",+ ),+ (+ "the user-visible generation wins even when nested",+ [+ {"event": "$ai_generation", "timestamp": T0},+ {"event": "$ai_span", "span_id": "s", "timestamp": T0 + timedelta(seconds=1)},+ {"event": "$ai_generation", "parent_id": "s", "timestamp": T0 + timedelta(seconds=2)},+ ],+ "e2",+ ),+ (+ "a trace event without state and without generations gives way to the first top-level node",+ [{"event": "$ai_trace", "timestamp": T0}, {"event": "$ai_span", "timestamp": T0 + timedelta(seconds=1)}],"e1",),("otherwise the first top-level node",[{"event": "$ai_span", "span_id": "s", "timestamp": T0},- {"event": "$ai_generation", "parent_id": "s", "timestamp": T0 + timedelta(seconds=1)},+ {"event": "$ai_span", "parent_id": "s", "timestamp": T0 + timedelta(seconds=1)},],"e0",),diff --git a/products/ai_observability/backend/tests/logic/traces/test_trace_queries.py b/products/ai_observability/backend/tests/logic/traces/test_trace_queries.pyindex ae039249bac6..d1695ed49ebe 100644--- a/products/ai_observability/backend/tests/logic/traces/test_trace_queries.py+++ b/products/ai_observability/backend/tests/logic/traces/test_trace_queries.py@@ -134,25 +134,35 @@ class TestLoadTrace(TraceEventsMixin, ClickhouseTestMixin, BaseTest):def test_ingested_values_read_like_the_legacy_view(self) -> None:self._ingest("00000000-0000-0000-0000-000000000001",- {"$ai_error": "", "$ai_input_tokens": {"total": 7}, "$ai_git_branch": ""},+ {+ "$ai_error": "",+ "$ai_input_tokens": {"total": 7},+ "$ai_input_state": None,+ "$ai_output_state": {},+ "$ai_git_branch": "",+ },+ event="$ai_trace",)self._ingest("00000000-0000-0000-0000-000000000002",{"$ai_error": {"message": "boom"},"$ai_input_tokens": 3,+ "$ai_output_state": {"answer": "hi"},"$ai_git_branch": "feat/rag","$ai_git_repo": "acme/app",},+ event="$ai_trace",)rows = load_trace(self.team, None, "trace-1", None).rowsassert sorted(- (row.uuid, row.error_is_truthy, row.input_tokens, row.git_branch, row.git_repo) for row in rows+ (row.uuid, row.error_is_truthy, row.input_tokens, row.has_state, row.git_branch, row.git_repo)+ for row in rows) == [- ("00000000-0000-0000-0000-000000000001", False, 7, None, None),- ("00000000-0000-0000-0000-000000000002", True, 3, "feat/rag", "acme/app"),+ ("00000000-0000-0000-0000-000000000001", False, 7, False, None, None),+ ("00000000-0000-0000-0000-000000000002", True, 3, True, "feat/rag", "acme/app"),]def test_person_comes_from_the_trace_event_distinct_id(self) -> None:@@ -362,7 +372,7 @@ class TestEventsFallback(TraceEventsMixin, ClickhouseTestMixin, BaseTest):"$ai_error": {"message": "boom"},"$ai_git_branch": "feat/rag",}- clean_span: dict[str, object] = {"$ai_error": "", "$ai_input_tokens": {"total": 7}}+ clean_span: dict[str, object] = {"$ai_error": "", "$ai_input_tokens": {"total": 7}, "$ai_output_state": None}bulk_create_events([self._event("00000000-0000-0000-0000-000000000001", properties=old_span),@@ -373,10 +383,11 @@ class TestEventsFallback(TraceEventsMixin, ClickhouseTestMixin, BaseTest):loaded = load_trace(self.team, None, "trace-1", timestamp_hint)assert sorted(- (row.uuid, row.span_name, row.error_is_truthy, row.input_tokens, row.git_branch) for row in loaded.rows+ (row.uuid, row.span_name, row.error_is_truthy, row.input_tokens, row.has_state, row.git_branch)+ for row in loaded.rows) == [- ("00000000-0000-0000-0000-000000000001", "old", True, None, "feat/rag"),- ("00000000-0000-0000-0000-000000000002", None, False, 7, None),+ ("00000000-0000-0000-0000-000000000001", "old", True, None, False, "feat/rag"),+ ("00000000-0000-0000-0000-000000000002", None, False, 7, False, None),]def test_hint_bounds_the_fallback_window(self) -> None: