尧图网页设计 
PostHog AI Observability 事件表 posthog.ai_events重属性分离、HogQL 命名空间与 LLM Trace 查询模式【免费下载链接】posthog: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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本篇以 PostHog 官方 skill 参考文档products/posthog_ai/skills/querying-posthog-data/references/models-ai-observability-events.md为主体讲清 LLM/AI 可观测性数据在 PostHog 中的双层存储设计轻量元数据留在共享的events表重内容输入输出消息、工具定义等落到专用 ClickHouse 表posthog.ai_events的原生列上。读完你可以直接写出正确的 HogQL 查询——包括为什么必须带posthog.前缀、哪些列在哪张表、以及按trace_id访问而非按时间扫描的两种标准查询模式。核心设计元数据与重内容分离LLM/AI 事件$ai_generation、$ai_span、$ai_trace、$ai_embedding、$ai_metric、$ai_feedback、$ai_evaluation首先被捕获到共享的events表上与其他所有产品事件共存。但重量级 LLM 属性不会存储在events上——它们作为原生列存放在专用的 ClickHouse 表posthog.ai_events中。这个分离并非逻辑抽象而是物理实现从 ClickHouse 建表 DDL 可以看到写入路径是一条 Kafka 物化视图ai_events_json_ws_mv。它在把行写入posthog.ai_events时会用JSONExtractKeysAndValuesRaw重建properties列并显式剔除六个重属性键-- posthog/clickhouse/hcl/sql/dev/ai_events.sql物化视图节选 arrayFilter( x - ((x.1) NOT IN ($ai_input, $ai_output, $ai_output_choices, $ai_input_state, $ai_output_state, $ai_tools)), JSONExtractKeysAndValuesRaw(src.properties) )也就是说ai_events.properties里天然不含这六个重键它们被JSONExtract*逐一抽取成独立原生列如JSONExtract(src.properties, $ai_model, Nullable(String)) AS model。查询侧因此可以按列裁剪读取避免每次都反序列化完整 JSON。命名空间必须写 posthog.ai_events在 HogQL 中引用这张表时必须写成posthog.ai_events而不能裸写ai_events。它和posthog.trace_spans、posthog.metrics一样注册在 HogQL 数据库的posthog.命名空间下——见 database.pyposthog: TableNode( nameposthog, children{ **clone_root_tables(), ai_events: TableNode(nameai_events, tableAiEventsTable()), ... }, ),裸写FROM ai_events会在 HogQL 编译期直接报 Unknown table。文档特别指出这是一个不对称点events和logs注册在根层级root level无需前缀而ai_events需要。编写或生成查询时这是最容易踩的坑。列分布哪些列在哪张表events保留的是轻量元数据——token 数、成本、model、provider、$ai_trace_id、延迟、错误标记。这些属性同时以原生列的形式镜像在posthog.ai_events上其中$ai_前缀属性映射为去前缀的列名例如$ai_model→model。只有posthog.ai_events持有的重属性如下重内容events属性posthog.ai_events列输入消息$ai_inputinput输出$ai_outputoutput输出 choices$ai_output_choicesoutput_choices输入状态$ai_input_stateinput_state输出状态$ai_output_stateoutput_state工具定义$ai_toolstools没有哪个重列对事件类型有强制限制但典型形态是$ai_generation携带input/output_choices/toolsembedding 携带input$ai_span和$ai_trace携带input_state/output_state。完整原生列清单完整的原生列定义在 AiEventsTableposthog/hogql/database/schema/ai_events.py与 DDL 一一对应。按职责分组核心标识uuid、event、timestamp、team_id、distinct_id、person_id、properties、retention_days默认 30DDL 中为retention_days Int16 DEFAULT 30。Trace 结构trace_id非空、session_id、parent_id、span_id、span_type、generation_id、experiment_id以及可读名称span_name、trace_name、prompt_name。模型信息model、provider、frameworkDDL 中为LowCardinality(Nullable(String))因为基数低、过滤频繁。Token 计数total_tokens、input_tokens、output_tokens以及按模态细分的text/image/audio/video_input_tokens、*_output_tokens还有reasoning_tokens推理 token、cache_read_input_tokens/cache_creation_input_tokensprovider prompt cache 命中/写入、web_search_count。成本USDinput_cost_usd、output_cost_usd、total_cost_usd、request_cost_usd以及web_search_cost_usd、audio_cost_usd、image_cost_usd、video_cost_usd。时延latency端到端秒、time_to_first_token首 token 时间秒。错误is_errorUInt8、error原始错误信息、error_typeLowCardinality 分类、error_normalized归一化分组串用于聚合。重内容列input、output、output_choices、input_state、output_state、tools——全部是StringJSONDatabaseFieldHogQL 会透过底层的 JSONExtract 支持数组/对象路径访问。此外还有一个隐藏的_timestamp列Kafka 消费者写入 ClickHouse 的时间被标记为hiddenTrue不出现在用户可见 schema 中仅供内部做摄入延迟ingestion-lag感知检查它与客户端可设置的timestamp不同不受客户端时钟影响。Schema 还注册了pdi懒连接与person字段遍历器可以从事件经person_distinct_ids关联到人通过person.properties.*访问。访问模式trace_id 才是访问路径posthog.ai_events的排序键是ORDER BY (team_id, trace_id, timestamp)DDL 中为 ReplicatedMergeTreePARTITION BY toYYYYMM(drop_date) TTL drop_date且ttl_only_drop_parts 1按整分区删除过期数据。因此trace_id是访问路径而不是timestamp按trace_id过滤能命中排序键前缀在给定 team 下表上还建有辅助索引其中trace_id是bloom_filter(0.001) GRANULARITY 1DDL 第 65 行event、is_error、provider等低基数列用set索引span_id/session_id/model等用 bloom filter。同时注意保留期约束行在保留期默认 30 天后被删除超过保留期的 trace 不再有内容——即使events表里还留有该事件的元数据行去ai_events也取不到重内容。单条 trace已知 ID直接读取SELECT timestamp, span_id, event, model, input, output_choices FROM posthog.ai_events WHERE trace_id trace_id ORDER BY timestamp批量/分析跨多个 trace 的时间窗口两跳查询先用带 timestamp 索引的events表做时间窗过滤、拿到 trace ID 集合再锚定trace_id去posthog.ai_events取重内容WITH matching_traces AS ( SELECT DISTINCT properties.$ai_trace_id AS trace_id FROM events WHERE event $ai_generation AND timestamp now() - INTERVAL 7 DAY AND properties.$ai_model gpt-4o ) SELECT a.trace_id, a.span_id, a.model, a.input, a.output_choices FROM posthog.ai_events AS a WHERE a.trace_id IN (SELECT trace_id FROM matching_traces) ORDER BY a.trace_id, a.timestamp这个模式的要点时间条件timestamp ...放在第一跳的events上利用其时间索引做预过滤ai_events上只保留排序键友好的trace_id IN (...)条件。反过来在ai_events上直接按时间窗全表扫描会绕开排序键效率更差。何时用类型化工具何时手写 HogQL参考文档给出了一条选择准则与 PostHog MCP/Agent 侧的工具编排一致posthog:query-llm-trace单个 trace和posthog:query-llm-traces-listtrace 列表这两个类型化工具内部都会替你去 joinposthog.ai_events能覆盖就优先使用只有当你需要自定义聚合、join、或类型化工具没有暴露的预过滤时才直接走 HogQL例如上面的批量两跳查询、按error_normalized分组统计失败率、按provider/framework下钻成本等。这些查询最终都通过该 skill 的posthog:execute-sql通道执行——products/posthog_ai/skills/querying-posthog-data/SKILL.md规定了完整的发现流程先看 schema 参考、找相近示例、再运行而本文对应的这份参考文件就是其中Data Schema一节里 AI observability 事件的权威列清单。小结三条可操作的规则命名空间HogQL 里写posthog.ai_events裸写会编译期失败列选择token/成本/模型/错误等轻量元数据两张表都能取ai_events上更快input/output/tools等重内容只存在于ai_events原生列访问路径有 trace ID 就按trace_id直查跨 trace 分析就用events时间窗预过滤 trace_id IN (...)两跳并牢记内容保留期默认 30 天。参考文件索引参考文档原文HogQL 表 Schema 定义HogQL 数据库命名空间注册ClickHouse DDL 与摄入物化视图querying-posthog-data skill 入口【免费下载链接】posthog: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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PostHog AI Observability 事件表 posthog.ai_events：重属性分离、HogQL 命名空间与 LLM Trace 查询模式
PostHog AI Observability 事件表 posthog.ai_events重属性分离、HogQL 命名空间与 LLM Trace 查询模式【免费下载链接】posthog: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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本篇以 PostHog 官方 skill 参考文档products/posthog_ai/skills/querying-posthog-data/references/models-ai-observability-events.md为主体讲清 LLM/AI 可观测性数据在 PostHog 中的双层存储设计轻量元数据留在共享的events表重内容输入输出消息、工具定义等落到专用 ClickHouse 表posthog.ai_events的原生列上。读完你可以直接写出正确的 HogQL 查询——包括为什么必须带posthog.前缀、哪些列在哪张表、以及按trace_id访问而非按时间扫描的两种标准查询模式。核心设计元数据与重内容分离LLM/AI 事件$ai_generation、$ai_span、$ai_trace、$ai_embedding、$ai_metric、$ai_feedback、$ai_evaluation首先被捕获到共享的events表上与其他所有产品事件共存。但重量级 LLM 属性不会存储在events上——它们作为原生列存放在专用的 ClickHouse 表posthog.ai_events中。这个分离并非逻辑抽象而是物理实现从 ClickHouse 建表 DDL 可以看到写入路径是一条 Kafka 物化视图ai_events_json_ws_mv。它在把行写入posthog.ai_events时会用JSONExtractKeysAndValuesRaw重建properties列并显式剔除六个重属性键-- posthog/clickhouse/hcl/sql/dev/ai_events.sql物化视图节选 arrayFilter( x - ((x.1) NOT IN ($ai_input, $ai_output, $ai_output_choices, $ai_input_state, $ai_output_state, $ai_tools)), JSONExtractKeysAndValuesRaw(src.properties) )也就是说ai_events.properties里天然不含这六个重键它们被JSONExtract*逐一抽取成独立原生列如JSONExtract(src.properties, $ai_model, Nullable(String)) AS model。查询侧因此可以按列裁剪读取避免每次都反序列化完整 JSON。命名空间必须写 posthog.ai_events在 HogQL 中引用这张表时必须写成posthog.ai_events而不能裸写ai_events。它和posthog.trace_spans、posthog.metrics一样注册在 HogQL 数据库的posthog.命名空间下——见 database.pyposthog: TableNode( nameposthog, children{ **clone_root_tables(), ai_events: TableNode(nameai_events, tableAiEventsTable()), ... }, ),裸写FROM ai_events会在 HogQL 编译期直接报 Unknown table。文档特别指出这是一个不对称点events和logs注册在根层级root level无需前缀而ai_events需要。编写或生成查询时这是最容易踩的坑。列分布哪些列在哪张表events保留的是轻量元数据——token 数、成本、model、provider、$ai_trace_id、延迟、错误标记。这些属性同时以原生列的形式镜像在posthog.ai_events上其中$ai_前缀属性映射为去前缀的列名例如$ai_model→model。只有posthog.ai_events持有的重属性如下重内容events属性posthog.ai_events列输入消息$ai_inputinput输出$ai_outputoutput输出 choices$ai_output_choicesoutput_choices输入状态$ai_input_stateinput_state输出状态$ai_output_stateoutput_state工具定义$ai_toolstools没有哪个重列对事件类型有强制限制但典型形态是$ai_generation携带input/output_choices/toolsembedding 携带input$ai_span和$ai_trace携带input_state/output_state。完整原生列清单完整的原生列定义在 AiEventsTableposthog/hogql/database/schema/ai_events.py与 DDL 一一对应。按职责分组核心标识uuid、event、timestamp、team_id、distinct_id、person_id、properties、retention_days默认 30DDL 中为retention_days Int16 DEFAULT 30。Trace 结构trace_id非空、session_id、parent_id、span_id、span_type、generation_id、experiment_id以及可读名称span_name、trace_name、prompt_name。模型信息model、provider、frameworkDDL 中为LowCardinality(Nullable(String))因为基数低、过滤频繁。Token 计数total_tokens、input_tokens、output_tokens以及按模态细分的text/image/audio/video_input_tokens、*_output_tokens还有reasoning_tokens推理 token、cache_read_input_tokens/cache_creation_input_tokensprovider prompt cache 命中/写入、web_search_count。成本USDinput_cost_usd、output_cost_usd、total_cost_usd、request_cost_usd以及web_search_cost_usd、audio_cost_usd、image_cost_usd、video_cost_usd。时延latency端到端秒、time_to_first_token首 token 时间秒。错误is_errorUInt8、error原始错误信息、error_typeLowCardinality 分类、error_normalized归一化分组串用于聚合。重内容列input、output、output_choices、input_state、output_state、tools——全部是StringJSONDatabaseFieldHogQL 会透过底层的 JSONExtract 支持数组/对象路径访问。此外还有一个隐藏的_timestamp列Kafka 消费者写入 ClickHouse 的时间被标记为hiddenTrue不出现在用户可见 schema 中仅供内部做摄入延迟ingestion-lag感知检查它与客户端可设置的timestamp不同不受客户端时钟影响。Schema 还注册了pdi懒连接与person字段遍历器可以从事件经person_distinct_ids关联到人通过person.properties.*访问。访问模式trace_id 才是访问路径posthog.ai_events的排序键是ORDER BY (team_id, trace_id, timestamp)DDL 中为 ReplicatedMergeTreePARTITION BY toYYYYMM(drop_date) TTL drop_date且ttl_only_drop_parts 1按整分区删除过期数据。因此trace_id是访问路径而不是timestamp按trace_id过滤能命中排序键前缀在给定 team 下表上还建有辅助索引其中trace_id是bloom_filter(0.001) GRANULARITY 1DDL 第 65 行event、is_error、provider等低基数列用set索引span_id/session_id/model等用 bloom filter。同时注意保留期约束行在保留期默认 30 天后被删除超过保留期的 trace 不再有内容——即使events表里还留有该事件的元数据行去ai_events也取不到重内容。单条 trace已知 ID直接读取SELECT timestamp, span_id, event, model, input, output_choices FROM posthog.ai_events WHERE trace_id trace_id ORDER BY timestamp批量/分析跨多个 trace 的时间窗口两跳查询先用带 timestamp 索引的events表做时间窗过滤、拿到 trace ID 集合再锚定trace_id去posthog.ai_events取重内容WITH matching_traces AS ( SELECT DISTINCT properties.$ai_trace_id AS trace_id FROM events WHERE event $ai_generation AND timestamp now() - INTERVAL 7 DAY AND properties.$ai_model gpt-4o ) SELECT a.trace_id, a.span_id, a.model, a.input, a.output_choices FROM posthog.ai_events AS a WHERE a.trace_id IN (SELECT trace_id FROM matching_traces) ORDER BY a.trace_id, a.timestamp这个模式的要点时间条件timestamp ...放在第一跳的events上利用其时间索引做预过滤ai_events上只保留排序键友好的trace_id IN (...)条件。反过来在ai_events上直接按时间窗全表扫描会绕开排序键效率更差。何时用类型化工具何时手写 HogQL参考文档给出了一条选择准则与 PostHog MCP/Agent 侧的工具编排一致posthog:query-llm-trace单个 trace和posthog:query-llm-traces-listtrace 列表这两个类型化工具内部都会替你去 joinposthog.ai_events能覆盖就优先使用只有当你需要自定义聚合、join、或类型化工具没有暴露的预过滤时才直接走 HogQL例如上面的批量两跳查询、按error_normalized分组统计失败率、按provider/framework下钻成本等。这些查询最终都通过该 skill 的posthog:execute-sql通道执行——products/posthog_ai/skills/querying-posthog-data/SKILL.md规定了完整的发现流程先看 schema 参考、找相近示例、再运行而本文对应的这份参考文件就是其中Data Schema一节里 AI observability 事件的权威列清单。小结三条可操作的规则命名空间HogQL 里写posthog.ai_events裸写会编译期失败列选择token/成本/模型/错误等轻量元数据两张表都能取ai_events上更快input/output/tools等重内容只存在于ai_events原生列访问路径有 trace ID 就按trace_id直查跨 trace 分析就用events时间窗预过滤 trace_id IN (...)两跳并牢记内容保留期默认 30 天。参考文件索引参考文档原文HogQL 表 Schema 定义HogQL 数据库命名空间注册ClickHouse DDL 与摄入物化视图querying-posthog-data skill 入口【免费下载链接】posthog: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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考