Back to Details

exploring-apm-traces

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Exploring APM traces (OpenTelemetry spans)

探索APM追踪（OpenTelemetry spans）

PostHog captures distributed traces from OpenTelemetry. Each trace is a tree of spans representing a request’s path through services.
Disambiguation: This skill is for APM / OpenTelemetry traces. Do not confuse with LLM analytics traces (agent/model 
$ai_*
events and LLM observability tools) or logs (
posthog:query-logs
, 
posthog:logs-*
).
PostHog 采集来自 OpenTelemetry 的分布式追踪数据。每个追踪都是由span组成的树状结构，代表请求在各个服务间的路径。
说明： 本技能适用于APM / OpenTelemetry 追踪。请勿与LLM分析追踪（智能体/模型的
$ai_*
事件及LLM可观测性工具）或日志（
posthog:query-logs
、
posthog:logs-*
）混淆。

MCP tools

MCP工具

ToolPurpose
posthog:query-apm-spans
Search and filter spans (analytics-style query; parameters live under 
query
)
posthog:apm-trace-get
Fetch all spans for a hex 
trace_id
posthog:apm-services-list
List distinct service names
posthog:apm-attributes-list
List span or resource attribute keys
posthog:apm-attribute-values-list
List values for a specific attribute key
For aggregates or joins not covered by these tools, 
posthog:execute-sql
may be appropriate once the span schema is confirmed for the project.
工具名称用途
posthog:query-apm-spans
搜索和过滤span（类分析查询；参数位于
query
字段下）
posthog:apm-trace-get
根据十六进制
trace_id
获取该追踪下的所有span
posthog:apm-services-list
列出所有不同的服务名称
posthog:apm-attributes-list
列出span或资源属性的键名
posthog:apm-attribute-values-list
列出指定属性键对应的所有值
如果这些工具无法满足聚合或关联需求，在确认项目的span schema后，
posthog:execute-sql
可能是合适的选择。

Span data model

Span数据模型

FieldDescription
trace_id
Hex ID linking spans in one trace
span_id
Hex ID for this span
parent_span_id
Parent span hex ID (null for root)
name
Operation name (e.g. 
HTTP GET /api/users
)
kind
0=Unspecified, 1=Internal, 2=Server, 3=Client, 4=Producer, 5=Consumer
service_name
Emitting service
status_code
0=Unset, 1=OK, 2=Error
timestamp
Start time (ISO 8601)
end_time
End time (ISO 8601)
duration_nano
Duration in nanoseconds
is_root_span
Whether this is the trace entry
字段名描述
trace_id
关联同一追踪中所有span的十六进制ID
span_id
当前span的十六进制ID
parent_span_id
父span的十六进制ID（根span为null）
name
操作名称（例如
HTTP GET /api/users
）
kind
类型：0=未指定，1=内部，2=服务端，3=客户端，4=生产者，5=消费者
service_name
发送span的服务名称
status_code
状态码：0=未设置，1=正常，2=错误
timestamp
开始时间（ISO 8601格式）
end_time
结束时间（ISO 8601格式）
duration_nano
持续时间（纳秒）
is_root_span
是否为追踪的入口span

Property filter types (
query.filterGroup
)

属性过滤类型（
query.filterGroup
）

  • span
    — built-in fields: 
    trace_id
    , 
    span_id
    , 
    duration
    , 
    name
    , 
    kind
    , 
    status_code
  • span_attribute
    — span-level attributes (e.g. 
    http.method
    )
  • span_resource_attribute
    — resource attributes (e.g. Kubernetes labels)
  • span
    — 内置字段：
    trace_id
    、
    span_id
    、
    duration
    、
    name
    、
    kind
    、
    status_code
  • span_attribute
    — span级属性（例如
    http.method
    ）
  • span_resource_attribute
    — 资源属性（例如Kubernetes标签）

Workflow: investigate slow requests

工作流：排查缓慢请求

  1. Discover services: call 
    posthog:apm-services-list
    with 
    {}
    (or applicable filters per tool schema).
  2. Find slow spans: 
    posthog:query-apm-spans
    with a 
    query
    that filters by service and 
    duration
    (remember nanoseconds: 1s = 1_000_000_000).
  3. Drill in: 
    posthog:apm-trace-get
    with 
    { "trace_id": "<hex from step 2>" }
    .
  1. 发现服务：调用
    posthog:apm-services-list
    并传入
    {}
    （或根据工具schema传入适用的过滤器）。
  2. 查找慢span：使用
    posthog:query-apm-spans
    ，传入按服务和
    duration
    过滤的
    query
    （注意单位是纳秒：1秒=1_000_000_000）。
  3. 深入分析：调用
    posthog:apm-trace-get
    并传入
    { "trace_id": "<步骤2中获取的十六进制ID>" }
    。

Workflow: find error traces

工作流：查找错误追踪

Use 
posthog:query-apm-spans
with 
query.filterGroup
on 
status_code
exact
/ numeric operators as appropriate — OpenTelemetry status 2 means error.
使用
posthog:query-apm-spans
，在
query.filterGroup
中对
status_code
设置精确匹配或数值操作符——OpenTelemetry中状态码2表示错误。

Workflow: explore unknown attributes

工作流：探索未知属性

  1. posthog:apm-attributes-list
    — narrow keys (e.g. search 
    "http"
    ).
  2. posthog:apm-attribute-values-list
    — inspect values for a chosen key.
  3. Build filters in 
    posthog:query-apm-spans
    using the discovered keys.
  1. posthog:apm-attributes-list
    — 筛选键名（例如搜索
    "http"
    ）。
  2. posthog:apm-attribute-values-list
    — 查看指定键对应的所有值。
  3. 在
    posthog:query-apm-spans
    中使用发现的键构建过滤器。

Reminders

注意事项

  • Prefer discovering attribute keys and services before guessing filters.
  • Durations in filters are in nanoseconds.
  • query-apm-spans
    expects a 
    query
     wrapper object; defaults often assume a recent time window — tighten 
    query.dateRange
    when the question implies it.
  • 建议先发现属性键和服务，再尝试设置过滤器。
  • 过滤器中的持续时间单位为纳秒。
  • query-apm-spans
    需要传入**
    query
    **包装对象；默认通常假设最近的时间窗口——当问题涉及特定时间段时，需缩小
    query.dateRange
    的范围。