SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场exploring-llm-traces

exploring-llm-traces

智能体与模型

查看项目

更新于 10-15 18:41

技能介绍

Exploring LLM Traces

用途

该技能用于调试和检查 LLM/AI 智能体追踪。PostHog 将 LLM/AI 智能体活动记录为 trace，每个 trace 是一棵事件树，表示一次 AI 交互——从顶层智能体调用到各个 LLM API 调用。技能在用户粘贴 trace 或 session URL（如 /ai-observability/traces/<id>）时使用。

可用工具

  • posthog:query-llm-traces-list：搜索并列出 trace，可能返回较大的多 trace 负载。
  • posthog:query-llm-trace：按 ID 获取单个 trace 的完整事件树。
  • posthog:read-data-schema：在过滤前发现自定义事件/人属性。
  • posthog:execute-sql：针对复杂 trace 分析执行临时 SQL。

事件层级

$ai_trace（顶层容器）── $ai_span（逻辑分组，如“RAG 检索”“工具执行”）── $ai_generation（单次 LLM API 调用）与 $ai_embedding（嵌入创建）。事件通过 $ai_parent_id 链接到父级的 $ai_span_id 或 $ai_trace_id。

工作流：从 URL 调试 trace 或 session

  1. 分类 URL：先检查路径，不要把每个 UUID 值都当作 trace ID。/ai-observability/traces/<trace_id>（或旧路径 /llm-analytics/traces、/llm-observability/traces）是单个 trace，用 posthog:query-llm-trace 获取。/ai-observability/sessions/<session_id>（或旧路径）是 AI session，用 posthog:query-llm-traces-list 按事件属性 $ai_session_id 过滤获取。保留 URL 中的 date_from/date_to；若没有但有 timestamp，则以该时间戳为锚点查询前后 36 小时窗口；若都没有，使用默认如 {"date_from": "-7d"}。对精确 trace/session URL，跳过 schema 发现。
  2. 浏览 trace 摘要：浏览时显式设置 detail: "summary"，只返回事件元数据和摘要，不含对话内容。可获取每个事件类型、span 名称（$ai_span_name，即工具/步骤名）、延迟、错误标志、模型、父子关系及 _posthogUrl。
  3. 读取调查所需内容：确定 trace 后，请求 detail: "full" 以检查具体工具参数、模型接收的上下文或搜索对话内容。两种模式都执行响应大小限制，需检查省略与截断标记后再下结论。
  4. 用脚本解析大型完整详情结果：提供 print_summary.py、print_timeline.py、extract_span.py、extract_conversation.py、search_traces.py，均支持 MAX_LEN=N 环境变量控制截断（0 = 不限制）。

被扣留的属性

两个 trace 工具只返回 AI 负载，仅返回 PostHog 分类定义的 $ai_* 属性，加上 $ai_generation_id、$ai_cache_read_cost_usd、$ai_cache_creation_cost_usd、$ai_effort、$session_id、$lib、$lib_version。其他事件属性和人属性在两种详情模式下都被扣留，名名列在 _redactedKeys 中。$ai_base_url 和 $ai_request_url 会去掉查询字符串。被扣留属性在 PostHog 中不变，仍可作为过滤器，可在 UI 或用 execute-sql 读取。

调查模式

  • “智能体是否正确使用工具？”：找到工具调用的 $ai_span，检查 $ai_input_state、$ai_output_state、$ai_is_error。
  • “上下文是否正确？”：找到 LLM 做出决策的 $ai_generation，检查 $ai_input（LLM 看到的完整消息历史），查看前置 $ai_span 的 $ai_output_state。
  • “子智能体是否工作？”：在结构概览中找到其他 span 的子 span（$ai_parent_id），父 span 是编排器，子 span 是子智能体步骤，检查每个子项的 $ai_output_state 和 $ai_is_error。
  • “LLM 为何说 X？”：用 search_traces.py 搜索文本出现位置，再检查该 generation 的 $ai_input。

构建 UI 链接

始终向用户展示返回的 _posthogUrl。也可手动构建：https://app.posthog.com/ai-observability/traces/<trace_id>?timestamp=<url_encoded_timestamp>&event=<optional_event_id>。timestamp 参数必填，使用 trace 中最早事件的 createdAt 并 URL 编码。

查找 trace

用 posthog:query-llm-traces-list 并设 detail: "summary" 搜索过滤。关键：不要凭训练数据假设事件名、属性名或属性值。对开放式搜索和自定义过滤，先调用 posthog:read-data-schema 发现项目中实际存在的属性和值。例外：精确 AI 可观测性 trace/session URL 可直接用内置 $ai_trace_id / $ai_session_id 并跳过 schema 发现。

提示

  • 始终设置 dateRange，无时间范围查询慢。宽泛列表用窄窗口（-30m、-1h），按 trace ID 或特定属性值过滤的窄查询可用宽窗口（-7d、-30d）。
  • 响应中始终包含 _posthogUrl。
  • span 上的 $ai_input_state / $ai_output_state 包含工具调用输入输出。
  • generation 上的 $ai_input / $ai_output_choices 包含完整 LLM 对话，可能达数兆字节；持久化到文件时使用解析脚本。
  • 原始 SQL 中，重内容只存在于 posthog.ai_events 表，不在 events.properties。
  • 搜索时用 filterTestAccounts: true 排除内部/测试流量。
  • $ai_trace 事件不在 events 数组中，其数据通过 trace 级 inputState、outputState 和 traceName 呈现。

适用场景与限制

适用于基于 PostHog 记录的 LLM/AI 智能体追踪的调试与检查。限制：功能依赖 PostHog MCP 工具与对应数据；被扣留属性、摘要省略或截断的内容无法通过脚本恢复；缺失事实暂未提供。