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): open stateless traces on the user-visible generation (#123530)

Carlos Marchalc77538825cc8
diff --git a/posthog/hogql/ACCESS_CONTROL.md b/posthog/hogql/ACCESS_CONTROL.md
index 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 d
The 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.py
index 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.py
index 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_name
self.event_prop.save()
@@ -415,7 +416,7 @@ class TestRestrictPropertiesInHogQL(BaseTest):
assert "NULL AS restricted_value" in sql
assert "JSONExtract" not in sql
- assert expression.split("[")[0] not in sql
+ assert (printed_column or expression.split("[")[0]) not in sql
def 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.py
index f3e6a38d4531..4c119ff0f1a6 100644
--- a/posthog/hogql/restricted_properties.py
+++ b/posthog/hogql/restricted_properties.py
@@ -6,7 +6,7 @@ from posthog.hogql import ast
from posthog.hogql.constants import FEATURE_FLAG_PROPERTY_PREFIX
from posthog.hogql.context import HogQLContext
from 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, AiEventsTable
from posthog.hogql.database.schema.events import EventsGroupSubTable, EventsPersonSubTable, EventsTable
from posthog.hogql.database.schema.flag_evaluations import FlagEvaluationsPersonSubTable, FlagEvaluationsTable
from 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.py
index 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_property
def 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_property
def 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.py
index 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 json
import math
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Iterable, Sequence
from dataclasses import replace
from datetime import datetime
from functools import reduce
@@ -63,6 +63,7 @@ class TraceEventRow:
latency: float | None
is_error: bool
error_is_truthy: bool
+ has_state: bool
ingestion_source: str | None
git_branch: str | None
git_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.py
index 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.py
index 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.py
index 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).rows
assert 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: