netra-mcp-usage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Netra MCP Usage

Netra MCP 使用指南

Use this skill when you need to inspect traces through Netra MCP tools and want precise, schema-correct inputs.

当你需要通过Netra MCP工具检查跟踪数据，且需要精准、符合Schema规范的输入时，可使用本Skill。

Scope

适用范围

Query traces in a time range with filtering, sorting, and cursor pagination.
Retrieve full span trees for a selected trace id.
Guide incident/debug workflows from trace search to root-cause analysis.

在时间范围内结合过滤、排序和游标分页查询跟踪数据。
检索指定trace id的完整调用链树。
指导从跟踪搜索到根因分析的事件排查/调试工作流。

Primary MCP Tools

核心MCP工具

```
mcp_netra_netra_query_traces
```
```
mcp_netra_netra_get_trace_by_id
```

```
mcp_netra_netra_query_traces
```
```
mcp_netra_netra_get_trace_by_id
```

Workflow

工作流

Start with a narrow time window and low limit.
Add the minimum filters needed to isolate relevant traces.
Sort for your objective (recent, slowest, most expensive, errors).
Page through results using returned cursor values.
Fetch full spans for one trace id.
Inspect hierarchy, status, latency, and attributes.

从窄时间窗口和低限制值开始。
添加最少必要的过滤条件以隔离相关跟踪数据。
根据目标进行排序（最新、最慢、成本最高、错误项）。
使用返回的cursor值翻页查看结果。
获取单个trace id的完整调用链。
检查层级结构、状态、延迟及属性。

query_traces Input Schema

query_traces 输入Schema

Required:

```
startTime
```
(string, ISO 8601)
```
endTime
```
(string, ISO 8601)

Optional:

```
limit
```
(number, 1-100, default 20)
```
cursor
```
(string)
```
direction
```
(
```
up
```
|
```
down
```
, default
```
down
```
)
```
sortField
```
```
sortOrder
```
(
```
asc
```
|
```
desc
```
, default
```
desc
```
)
```
filters
```
(array of filter objects)

必填项：

```
startTime
```
（字符串，ISO 8601格式）
```
endTime
```
（字符串，ISO 8601格式）

可选项：

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

sortField Values

sortField 可选值

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

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

Filter Object Schema

过滤对象Schema

Each filter object must include:

```
field
```
```
value
```
```
type
```
```
operator
```

Optional in filter object:

```
key
```
(for nested/object-style filtering)

每个过滤对象必须包含：

```
field
```
```
value
```
```
type
```
```
operator
```

过滤对象中的可选项：

```
key
```
（用于嵌套/对象式过滤）

field Values

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
```

```
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 Values

type 可选值

```
string
```
```
number
```
```
boolean
```
```
arrayOptions
```
```
attributeKey
```
```
object
```

```
string
```
```
number
```
```
boolean
```
```
arrayOptions
```
```
attributeKey
```
```
object
```

operator Values

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
```

```
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
```

Filter Patterns

过滤模式示例

Error traces only:

field: has_error

type: boolean

operator: equals

value: true

Specific session:

field: session_id

type: string

operator: equals

value: <session-id>

High latency:

field: latency

type: number

operator: greater_than

value: 3000

Service scoped:

field: service

type: string

operator: equals

value: <service-name>

Metadata key/value:

field: metadata

type: object

key: <metadata-key>

operator: equals

value: <value>

仅查询错误跟踪数据：

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>

Pagination Pattern

分页模式

Run
```
query_traces
```
without
```
cursor
```
.
Capture a
```
cursor
```
from returned trace items.
Re-run
```
query_traces
```
with the cursor and
```
direction: down
```
.
Continue while
```
pageInfo.hasNextPage
```
is true.

不带
```
cursor
```
参数调用
```
query_traces
```
。
从返回的跟踪项中获取
```
cursor
```
值。
使用该cursor并设置
```
direction: down
```
重新调用
```
query_traces
```
。
当
```
pageInfo.hasNextPage
```
为true时，继续上述操作。

get_trace_by_id Input Schema

get_trace_by_id 输入Schema

Required:

```
traceId
```
(string)

Behavior:

Returns complete span array for the trace id.
Use this after
```
query_traces
```
to inspect one trace deeply.
Invalid ids return a not-found style error.

必填项：

```
traceId
```
（字符串）

行为说明：

返回指定trace id的完整调用链数组。
在
```
query_traces
```
之后使用此接口深入检查单个跟踪数据。
无效id会返回未找到类错误。

Incident Triage Recipe

事件排查流程

Query for failing traces (
```
has_error=true
```
) in the incident window.
Sort by
```
latency_ms
```
desc to identify worst requests.
Pull one trace via
```
get_trace_by_id
```
.
Validate root span presence and parent-child span flow.
Check slow spans and tool/model metadata.
Compare with a nearby successful trace if needed.

在事件发生的时间窗口内查询失败的跟踪数据（
```
has_error=true
```
）。
按
```
latency_ms
```
降序排序，识别最耗时的请求。
通过
```
get_trace_by_id
```
获取一条跟踪数据。
验证根调用链是否存在及父子调用链的流转。
检查慢调用链及工具/模型元数据。
如有需要，与附近的成功跟踪数据进行对比。

Practical Tips

实用技巧

Keep initial windows short (5-30 minutes) for faster narrowing.
Use one or two filters first, then add more only if needed.
Prefer exact-match IDs (
```
session_id
```
,
```
user_id
```
,
```
tenant_id
```
) when available.
Use
```
sortField=total_cost
```
to find expensive traces quickly.
If no results: widen time range first, then relax filters.

初始时间窗口保持较短（5-30分钟），以便更快缩小范围。
先使用1-2个过滤条件，仅在必要时添加更多。
当有可用的精确匹配ID（如
```
session_id
```
、
```
user_id
```
、
```
tenant_id
```
）时，优先使用。
使用
```
sortField=total_cost
```
快速定位高成本跟踪数据。
若无查询结果：先扩大时间范围，再放宽过滤条件。