Netra MCP Usage

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

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.

Primary MCP Tools

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

query_traces Input 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)

sortField Values

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

Filter Object Schema

Each filter object must include:

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

Optional in filter object:

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

field Values

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

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

operator Values

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

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.

get_trace_by_id Input 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.

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.

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.

netra-mcp-usage

NPX Install

Tags

SKILL.md Content