netra-mcp-usage

Netra MCP 使用指南

需要通过 Netra MCP 工具检查跟踪记录，并希望使用精确、符合架构的输入时，请使用此技能。

范围

• 在指定时间范围内查询跟踪记录，并进行筛选、排序和游标分页。
• 获取所选跟踪 ID 的完整 Span 树。
• 获取会话级详细信息以及会话中的所有跟踪记录。
• 指导从搜索跟踪记录到根因分析的事件排查／调试工作流。

主要 MCP 工具

• netra_query_traces
• netra_get_trace_by_id
• netra_get_session_details

工作流

1. 从较短的时间窗口和较低的数量限制开始。
2. 添加隔离相关跟踪记录所需的最少筛选条件。
3. 根据目标排序（最新、最慢、成本最高、错误）。
4. 使用返回的游标值翻页浏览结果。
5. 获取某个跟踪 ID 的完整 Span。
6. 检查层级结构、状态、延迟和属性。
7. 需要获取会话的所有跟踪记录或会话级成本／令牌总量时，使用 get_session_details。

query_traces 输入架构

必填：

• startTime（字符串，ISO 8601）
• endTime（字符串，ISO 8601）

可选：

• limit（数字，1-100，默认值为 20）
• cursor（字符串）
• direction（up | down，默认值为 down）
• sortField
• sortOrder（asc | desc，默认值为 desc）
• filters（筛选对象数组）

sortField 值

• latency_ms
• name
• total_cost
• has_pii
• has_violation
• start_time
• environment
• service
• has_error
• total_tokens

筛选对象架构

每个筛选对象必须包含：

• field
• value
• type
• operator

筛选对象中的可选项：

• key（用于嵌套／对象式筛选）

field 值

• name
• tenant_id
• user_id
• session_id
• environment
• service
• metadata
• projectIds
• project_id
• parent_span_id
• has_pii
• has_violation
• has_error
• models
• total_cost
• latency

type 值

• string
• number
• boolean
• arrayOptions
• attributeKey
• object

operator 值

• equals
• greater_than
• less_than
• greater_equal_to
• less_equal_to
• contains
• not_equals
• any_of
• none_of
• not_contains
• starts_with
• ends_with
• is_null
• is_not_null

筛选模式

• 仅错误跟踪记录：
  • field: has_error、type: boolean、operator: equals、value: true
• 指定会话：
  • field: session_id、type: string、operator: equals、value: <session-id>
• 高延迟：
  • field: latency、type: number、operator: greater_than、value: 3000
• 按服务筛选：
  • field: service、type: string、operator: equals、value: <service-name>
• 元数据键／值：
  • field: metadata、type: object、key: <metadata-key>、operator: equals、value: <value>

分页模式

1. 不带 cursor 运行 query_traces。
2. 从返回的跟踪条目中获取 cursor。
3. 使用该游标和 direction: down 重新运行 query_traces。
4. 当 pageInfo.hasNextPage 为 true 时继续。

get_trace_by_id 输入架构

必填：

• traceId（字符串）

行为：

• 返回该跟踪 ID 的完整 Span 数组。
• 使用此工具深入检查一条跟踪记录，通常在运行 query_traces 之后使用。
• 无效 ID 会返回类似“未找到”的错误。

get_session_details 输入架构

必须且只能提供以下其中一项：

• session_id（字符串，可选）：要检索的会话 ID。
• trace_id（字符串，可选）：属于目标会话的跟踪 ID。系统会自动解析父会话。

两项都不提供或同时提供都会报错。

可选：

• startTime（字符串，ISO 8601）：时间范围的起始时间。默认为组织的数据保留窗口。
• endTime（字符串，ISO 8601）：时间范围的结束时间。默认为当前时间。
• include_raw_inputs（布尔值，默认值为 false）：若为 true，则包含每条跟踪记录的完整 Span 详细信息。可能会产生很大的响应。
• limit（数字，1-100，默认值为 50）：每页最多返回的跟踪记录数。
• cursor（字符串）：上一条响应中的分页游标。

行为说明

• 会话中的追踪按 start_time 升序排序。
• 如果会话中任一追踪的 has_error=true，则 status 为 errored；否则为 completed。
• totals 汇总所有返回追踪的成本、输入令牌数和输出令牌数。
• 分页方式与 query_traces 相同：传入返回的 cursor 以获取下一页。

会话查询模式

• 按会话 ID 查询：
  • session_id: <session-id>
• 按追踪 ID 查询（自动解析到其父会话）：
  • trace_id: <trace-id>
• 包含完整的 span 树：
  • session_id: <session-id>, include_raw_inputs: true

事故排查流程

1. 查询事故时间范围内失败的追踪（has_error=true）。
2. 按 latency_ms 降序排序，找出耗时最长的请求。
3. 通过 get_trace_by_id 获取一条追踪。
4. 验证根 span 是否存在，以及父子 span 的调用流程。
5. 检查耗时较长的 span，以及工具／模型元数据。
6. 如有需要，与时间相近的成功追踪进行比较。
7. 如果失败的追踪属于多轮会话，则使用 trace_id 调用 get_session_details，查看所有相关追踪、汇总成本，以及其他轮次是否也发生错误。

实用技巧

• 初始时间范围应尽量缩短（5-30 分钟），以便更快缩小排查范围。
• 先使用一两个筛选条件，仅在需要时再添加更多条件。
• 如果有精确匹配 ID（session_id、user_id、tenant_id），优先使用。
• 使用 sortField=total_cost 快速找出成本较高的追踪。
• 如果没有结果：先扩大时间范围，再放宽筛选条件。
• 如果已有 trace_id，但需要完整的会话上下文，请使用 trace_id 调用 get_session_details，而不要手动通过 query_traces 按 session_id 筛选。
• 谨慎使用 include_raw_inputs: true——它会获取会话中每条追踪的完整 span 树，数据量可能很大。
• 查看 session.status，即可快速判断会话中是否有追踪发生错误，无需逐条扫描。