netra-mcp-usage

Netra MCP の使い方

Netra MCP ツールを使ってトレースを調査し、正確でスキーマに準拠した入力を指定する必要がある場合に、このスキルを使用します。

対象範囲

• フィルタリング、並べ替え、カーソルによるページネーションを使って、指定した期間のトレースを検索します。
• 選択したトレース ID のスパンツリー全体を取得します。
• セッションレベルの詳細と、セッションに属するすべてのトレースを取得します。
• トレース検索から根本原因の分析まで、インシデントやデバッグのワークフローを案内します。

主な MCP ツール

• netra_query_traces
• netra_get_trace_by_id
• netra_get_session_details

ワークフロー

1. 狭い時間範囲と小さい上限値から始めます。
2. 関連するトレースを絞り込むために必要最小限のフィルタを追加します。
3. 目的（新しい順、遅い順、コストの高い順、エラー）に合わせて並べ替えます。
4. 返されたカーソル値を使って、結果をページごとに取得します。
5. 1 つのトレース ID のスパン全体を取得します。
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 のスパン配列全体を返します。
• 1 つのトレースを詳しく調べるには、query_traces の後に使用します。
• 無効な ID の場合は、見つからないことを示すエラーが返されます。

get_session_details の入力スキーマ

以下のうち、ちょうど 1 つを指定してください：

• session_id（文字列、任意）：取得するセッション ID です。
• trace_id（文字列、任意）：対象のセッションに属するトレース ID です。親セッションは自動的に解決されます。

どちらも指定しない場合、または両方を指定した場合はエラーになります。

任意：

• startTime（文字列、ISO 8601）：時間範囲の開始時刻です。デフォルトは組織のデータ保持期間です。
• endTime（文字列、ISO 8601）：時間範囲の終了時刻です。デフォルトは現在時刻です。
• include_raw_inputs（ブール値、デフォルトは false）：true の場合、各トレースのスパン詳細全体を含めます。応答が大きくなる可能性があります。
• limit（数値、1～100、デフォルトは 50）：1 ページあたりに返すトレースの最大数です。
• cursor（文字列）：前回の応答で返されたページネーション用カーソルです。

動作に関する注意事項

• セッション内のトレースは、start_time の昇順で並べ替えられます。
• セッション内のいずれかのトレースで has_error=true の場合、status は errored になり、それ以外の場合は completed になります。
• totals には、返されたすべてのトレースのコスト、入力トークン、出力トークンの合計が集計されます。
• ページネーションの動作は query_traces と同じです。次のページを取得するには、返された cursor を渡します。

セッションの検索パターン

• セッション ID で検索する場合：
  • session_id: <session-id>
• トレース ID で検索する場合（親セッションを自動的に解決します）：
  • trace_id: <trace-id>
• 完全なスパンツリーを含める場合：
  • session_id: <session-id>, include_raw_inputs: true

インシデントのトリアージ手順

1. インシデントの発生時間帯に has_error=true のトレースを検索します。
2. latency_ms の降順に並べ替えて、最も時間のかかるリクエストを特定します。
3. get_trace_by_id でトレースを 1 件取得します。
4. ルートスパンの有無と、親子スパンの流れを確認します。
5. 時間のかかるスパンと、ツール／モデルのメタデータを確認します。
6. 必要に応じて、近接する成功したトレースと比較します。
7. 失敗したトレースが複数ターンのセッションに属する場合は、trace_id を指定して get_session_details を呼び出し、関連するすべてのトレース、集計コスト、ほかのターンでもエラーが発生しているかどうかを確認します。

実用的なヒント

• 絞り込みを速めるため、最初は短い時間範囲（5～30 分）を指定します。
• まず 1 つか 2 つのフィルターを使い、必要な場合にのみ追加します。
• 利用できる場合は、完全一致する ID（session_id、user_id、tenant_id）を優先します。
• 高コストのトレースをすばやく見つけるには、sortField=total_cost を使用します。
• 結果がない場合は、まず時間範囲を広げてから、フィルターの条件を緩めます。
• trace_id があり、セッション全体のコンテキストが必要な場合は、query_traces を session_id で手動フィルタリングする代わりに、trace_id を指定して get_session_details を使用します。
• include_raw_inputs: true は必要な場合に限って使用してください。セッション内のすべてのトレースについて完全なスパンツリーを取得するため、非常に大きくなる場合があります。
• session.status を確認すれば、各トレースを個別に調べずに、セッション内のいずれかのトレースでエラーが発生したかどうかをすばやく判断できます。