traceway

Traceway

traceway CLI を使って、ターミナルから Traceway インスタンスを操作します。引数の最初の単語によってフローが決まります。

Invocation	Flow
/traceway login	ログイン：CLI がない場合はインストールし、認証して、プロジェクトを選択します
/traceway debug <issue ref or bug description>	デバッグ：問題を特定し、根本原因を調査します
/traceway perf <endpoint or symptom>	パフォーマンス：一般的なボトルネックのチェックリストに照らして、根本原因となるレイテンシや速度低下を診断します
/traceway <anything else>	クエリ：CLI でデータを読み取り、オブザーバビリティに関する質問に回答します
/traceway (no argument)	何をしたいかを尋ねます：ログイン、問題のデバッグ、またはクエリの実行

CLI は現在、活発に開発されています。ここに記載されたフラグが traceway <command> --help に表示されない場合は、バイナリの動作を優先してください。 traceway MCP サーバーが接続されている場合は、シェルから CLI を実行するよりも、そのツールを優先してください。同じ API を同じセマンティクスでラップしており、このスキルの知識もリソースとして利用できます。このサーバーは同じバイナリ（traceway mcp）です。 このスキルは読み取りのみを行います。問題のアーカイブ、ページの確認や解決、アラートのスヌーズ、モニターの実行、ポストモーテムの作成など、何かを変更するには、別途 traceway-write CLI と traceway-write スキルをインストールしてください。 Traceway の仕組み（スケジュール、エスカレーション、ステータスページ、アラートルール、影響スコアなど）について尋ねられた場合は、traceway-learn スキルを使ってください。製品の完全なガイドです。

基本ルール（すべてのフロー共通）

• 読み取りは安全です：list／show／query サブコマンドは自由に実行できます。サーバーの状態を変更することはありません。
• この CLI は読み取り専用です：traceway に状態を変更するコマンドはなく、ログインしても読み取りのみ可能です。変更（問題のアーカイブ、ページの確認、アラートのスヌーズ、ポストモーテムの編集）には、別途 traceway-write CLI と traceway-write スキルが必要です。「このエラーを見て」は、読み取るという意味であり、決して変更するという意味ではありません。
• 出力：パイプに渡す出力は、デフォルトで JSON（TTY ではテーブル）です。JSON と jq の使用を優先し、--fields a,b,c でレスポンスを絞り込んでください。トリアージでは --page-size を 10～20 にしてください。
• 時間範囲：クエリには必ず時間範囲を指定してください。「今」に関する質問ではデフォルトで --since 1h、それ以外では --since 24h を使います。--since では s、m、h、小文字の Nd を指定できます（1w や 7d2h は使えません）。絶対時間範囲は --from／--to（RFC3339）で指定します。
• 終了コード：0 は正常、1 は一般エラー／API エラー、2 は使用方法のエラー、3 は接続エラー、4 は認証エラー、5 は見つからない、6 はレート制限、7 はサーバーの 5xx エラーです。エラーは標準エラー出力に {"error":"<stable_id>","message":"...","hint":"...","exit_code":N} の形式で出力されます。error フィールドに基づいて分岐してください。
• 終了コードが 4（認証）の場合、自分で traceway login を実行しないでください。ログインフローに切り替え、ユーザーに認証情報を入力してもらってください。
• 修正方法を推測しないでください：テレメトリから障害の原因が分からない場合、推測に基づいて動作を変更しないでください。次回の調査で原因が分かるよう、必要な計測を追加し、未解明の点を伝えてください。「デバッグ」フローの「証拠が不十分な場合」を参照してください。

ダッシュボード URL の解決

ユーザーは、あらゆるフローで参照先としてダッシュボード URL（https://<instance>/<route>）を貼り付けます。パスの種類に応じて解決してください。

URL パス	識別対象	取得方法
/issues/<hash> および /issues/<hash>/events	例外グループ（hash = 16 桁の 16 進数）	traceway exceptions show <hash>
/issues/<hash>/<occurrenceId>（UUID）	グループ内の 1 件の発生	traceway exceptions occurrence <occurrenceId> --recorded-at <t>。t は URL の ?t= パラメーターです。直接取得でき、高速です。また、発生の sessionId とセッション記録も返します。URL がない場合は、traceway exceptions show <hash> の発生一覧から recordedAt を取得します
/endpoints/<endpoint>	エンドポイントグループ。セグメントは URL エンコードされたエンドポイント名です（GET%20%2Fapi%2Fusers%2F%3Aid は GET /api/users/:id です）	デコードしてから、traceway endpoints list --search "<decoded name>" を実行します（グループには ID がありません。endpoints show は 1 件のリクエストに使います。次の行を参照してください）
/endpoints/<endpoint>/<endpointId>	そのエンドポイントの 1 件のリクエスト（トランザクション）	traceway endpoints show <endpointId> --recorded-at <t>（t = URL の ?t= パラメーター）。リクエスト、そのスパンのウォーターフォール、関連する例外やメッセージがあれば、それらを返します
/tasks/<task>	バックグラウンドタスクグループ	グループを取得する CLI はありません。1 回の実行を取得するには次の行を使います
/tasks/<task>/<taskId>	1 回のタスク実行	traceway tasks show <taskId> --recorded-at <t>（t = URL の ?t= パラメーター）
/sessions/<sessionId>	セッション（その間に発生した例外。リプレイはダッシュボードのみ）	traceway sessions show <sessionId> --started-at <t>。URL に ?t= はありません。セッションの開始時刻、URL の from=、または関連する発生の recordedAt（時間枠内に収まります）を使います。発生は sessionId でセッションを参照します
/ai-traces/<traceName>	AI トレースグループ	グループを取得する CLI はありません。1 件のトレースを取得するには次の行を使います
/ai-traces/<traceName>/<traceId>	1 件の AI トレース	traceway ai-traces show <aiTraceId> --recorded-at <t>（URL 内の UUID を使います。32 桁の 16 進数の trace id ではありません）（t = URL の ?t= パラメーター）。トークン数とコストの統計、および会話を返します
/logs	ログページ（フィルターは URL に保存されません）	ユーザーの説明からフラグを指定して traceway logs query を実行します
/issues、/endpoints、/metrics、/	一覧ページおよびダッシュボードページ	対応する list / query コマンド

時間枠：ほとんどのダッシュボード URL には ?preset=<p> または ?from=<iso>&to=<iso> が含まれます（ページを移動しても引き継がれます）。デフォルトの時間枠ではなく、これらを適用してください。

• preset の値 5m 30m 60m 3h 6h 12h 24h 3d 7d は、そのまま --since に対応します。CLI に月単位はないため、1M は --since 30d、3M は --since 90d に変換します。
• from / to は ISO タイムスタンプです。CLI には RFC3339 形式が必要なため、末尾に Z（または適切なオフセット）がない場合は付加して、--from / --to で渡します。
• 時刻パラメーターがない場合、ページはデフォルトの時間枠で表示されています。基本ルールに従って --since を選択します。

preset / from / to は、一覧表示やグループ表示の 時間枠 を設定します。詳細 URL にはさらに、URL エンコードされた単一レコードのタイムスタンプ ?t=<iso> が含まれます。この t の値が、ID による取得コマンドで必要な --recorded-at（セッションの場合は --started-at）にそのまま使えます。次の「ID による高速検索」を参照してください。

高速な ID 検索（タイムスタンプを必ず指定してください）

ID による詳細コマンド（exceptions occurrence、endpoints show、tasks show、ai-traces show、sessions show、traces show）では、レコードのタイムスタンプ（--recorded-at、またはセッションの場合は --started-at）が必須です。テレメトリテーブルは日単位でパーティション分割されています。タイムスタンプを指定すると検索対象が小さな範囲に絞られ、ClickHouse は数個のパーティションだけを読み取ります。指定しない場合、サーバーはすべてのパーティションをスキャンします（コールドロードに時間がかかります）。この理由からフラグは必須です。決して省略しないでください。タイムスタンプは概算でもかまいません（±24 時間以内）。手元にない場合も、復元または推定できます。「タイムスタンプがない場合」を参照してください。

タイムスタンプの取得元は、優先度の高い順に次のとおりです。

1. ダッシュボードの URL：?t=<iso> パラメーターがレコードの recordedAt です。URL デコードして、そのまま渡してください（セッションには t がありません。セッションの開始時刻、from=、または関連する occurrence の recordedAt を使用してください）。
2. すでに取得したリスト／グループ：exceptions show の各 occurrence には recordedAt が含まれます。ID と recordedAt をセットで記録してから、詳細を確認してください。
3. 通知：以下を参照してください。

ID がわかっている場合のクエリ順序：まず recordedAt を特定し（URL、グループ、または通知から）、次にそれを指定して ID によるコマンドを実行します。

タイムスタンプがない場合

このフラグは必須なので、何らかの値を指定する必要がありますが、概算でもかまいません。検索ウィンドウは指定した時刻の**±24 時間**（traces show の場合は**±48 時間**）です。この範囲にレコードがない場合、サーバーは範囲を限定せずにスキャンします。つまり、実際の時刻から 1 日以内のタイムスタンプであれば高速に検索できます。推測が間違っていても、正しいレコードは返されますが、検索は遅くなります。次の順序で特定してください。

1. API から復元します。 ハッシュがわかっている occurrence（たとえば、?t= なしで貼り付けられた /issues/<hash>/<occurrenceId>）の場合、traceway exceptions show <hash> を実行し、その occurrence の recordedAt を確認してください。ハッシュエンドポイントにはタイムスタンプは不要です。exceptions list で取得したグループの firstSeen／lastSeen は、occurrence が発生した時期を示します（lastSeen は最新のものにほぼ相当します）。
2. 状況から推定します。 通知の送信時刻、issue の firstSeen／lastSeen、URL の preset／from ウィンドウは、いずれも ±24 時間の範囲に収まる手がかりになります。高速検索にはそれで十分です。
3. ユーザーに尋ねます。 時刻を絞り込む手がかりが何もない場合（たとえば、ハッシュも時刻もなく、復元できるリストもない occurrence／endpoint ID だけの場合）、おおよその発生時刻を尋ねてください（「これはだいたいいつ発生しましたか？ 1 日以内の範囲で十分です」）。その時刻を指定してください。issue が古いのに「now」のような仮の値を作らないでください。パーティションの絞り込みが機能せず、±24 時間の範囲から完全に外れてしまう可能性があります。

通知の特定

Traceway の通知（メール／Slack／Webhook）には 2 つの形式があります。本文を読んで見分けてください。例外通知には Hash: と Exception ID: が含まれます。パフォーマンス通知（レイテンシ、apdex、インパクト）には endpoint としきい値が記載され、ハッシュはありません。Webhook のペイロードには、ルールを正確に示す ruleType フィールドも含まれます。それぞれ異なる方法で特定してください。

例外通知

本文には、直接かつ高速に検索するために必要な情報がすべて含まれています。内容は次のとおりです。

• Hash: <16-hex> — 例外グループ → traceway exceptions show <hash>。
• Exception ID: <uuid> — 特定の occurrence。
• Occurred at: 2006-01-02 15:04:05 UTC — occurrence のタイムスタンプ。RFC3339 形式に変換してください：スペースを T に置き換え、 UTC を Z に置き換えます（→ 2006-01-02T15:04:05Z）。
• View details: <url> — 詳細へのディープリンクです。サーバーで APP_BASE_URL が設定されている場合は https://<instance>/issues/<hash>、設定されていない場合はパスのみの /issues/<hash> です。

通知からは、occurrence を直接検索して（高速）、同じタイムスタンプを再利用して関連情報を確認します。

traceway exceptions occurrence <Exception ID> --recorded-at <Occurred at → RFC3339> --output json
# the result carries traceId, relatedEntity and sessionId → traces show / endpoints show / sessions show below

パフォーマンス通知（エンドポイントが低速またはクリティカルになった場合）

これらの通知はエラーではなく、レイテンシー／スループットのルールによって発火します。ハッシュも例外 ID もなく、取得できる発生情報もありません。どのルールかは、Webhook の ruleType（または件名の文言）で判別できます。

ruleType	件名／本文の形式	詳細リンク
endpoint_p95_threshold / endpoint_p99_threshold	<endpoint> で P95 latency 1250ms · 「過去 N 分間に 1250ms に到達（しきい値：1000ms）」	/endpoints?from=<iso>&to=<iso>
apdex_drop	Apdex が 0.62 に低下（しきい値：0.80） · 「過去 N 分間の N 件のリクエスト全体」	/endpoints?from=<iso>&to=<iso>
impact_score_critical|high|medium	エンドポイント <endpoint> の影響度がクリティカルになりました · 「影響スコア：0.82。理由：」	/endpoints?from=<iso>&to=<iso>
metric_threshold	メトリクス <name> は <value> です（しきい値：gt 100）	/metrics?preset=1h

本文には、エンドポイント名（件名／本文から解析します。独立したフィールドではありません）、メトリクス／パーセンタイル、現在の値、しきい値、ルックバック期間が含まれます。/endpoints?from=&to= リンクは発火時刻前後の約 3 分間のみを示すため、発火時刻はインシデントの発生時刻の手がかりとして扱い、インシデントの時間帯そのものとはみなさないでください。

解決するには、発火時刻を時間の基準として、そのエンドポイントに絞ったパフォーマンスフローに直接引き継ぎます。

# 1. confirm the alert against current stats for that endpoint
traceway endpoints list --search "<endpoint>" --since 1h --output json | jq '.data[0] | {p50_ms: (.p50Duration / 1e6), p95_ms: (.p95Duration / 1e6), p99_ms: (.p99Duration / 1e6), count, impact, impactReason}'
# 2. is this an accepted baseline? check whether an operator marked it slow
traceway endpoints slow "<endpoint>" --output json    # {offsetMs, reason}; offsetMs 0 = not marked
# 3. find when it crossed the threshold, then a slow trace (see Flow: Performance)
traceway endpoints chart --metric-type p95 --since 6h --interval-minutes 15 --output json

ステップ 2 が重要です。impact_score_* または apdex_drop のアラートはすでにオフセットを考慮しますが、endpoint_p95_threshold / endpoint_p99_threshold は低速としてマークされているかどうかにかかわらず、生のレイテンシーで発火します。そのため、低速とマークされたエンドポイントでは、オペレーターがすでに許容しているレイテンシーでアラートが発生することがあります。performance.md の「ユーザーが低速としてマークしたエンドポイントを考慮する」を参照してください。

フロー：ログイン

1. インストール済みか確認する

traceway version

バージョンが表示された場合は、認証に進みます。

2. 未インストールの場合はインストールする

POSIX システム（Linux、macOS）では、インストールスクリプトを使用します。

curl -fsSL https://cli.tracewayapp.com/install.sh | sh

スクリプトを使用できない場合は、手動でインストールします。ビルド済みバイナリは tracewayapp/traceway のリリースページ の cli/vX.Y.Z タグにあります（最新リリースが Backend のリリースの場合があるため、CLI タグで絞り込んでください）。

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); [ "$ARCH" = "aarch64" ] && ARCH=arm64
URL=$(curl -s "https://api.github.com/repos/tracewayapp/traceway/releases?per_page=20" \
  | grep -o "https://[^\"]*traceway_[^\"]*_${OS}_${ARCH}\.tar\.gz" | head -1)
TMP=$(mktemp -d)
curl -sL "$URL" | tar -xz -C "$TMP"
install -m 755 "$TMP/traceway" ~/.local/bin/traceway && rm -rf "$TMP"

~/.local/bin が PATH に含まれていることを確認してください（または /usr/local/bin にインストールしてください）。代替手段として、ソースからビルドできます（Go が必要です）。

git clone https://github.com/tracewayapp/traceway && cd traceway/cli
go build -o bin/traceway ./cmd/traceway && install -m 755 bin/traceway ~/.local/bin/traceway

traceway version で確認します。

3. 認証する

ログイン時にはパスワードの対話入力が求められるため、ユーザー自身に実行してもらってください（Claude Code では、出力がセッションに表示されるよう ! traceway login --url https://<instance> と入力することを提案してください）。

traceway login --url https://<traceway-instance>

パスワードがシークレットストアにある場合は、非対話型の方法を使えます（パスワードをコマンドラインやシェルの履歴に絶対に出力しないでください）。

printf '%s' "$TRACEWAY_PASSWORD" | traceway login --url https://<instance> --username [email protected] --password-stdin

複数のインスタンスやアカウントは、プロファイルを使って共存できます。traceway login --url ... --profile work を実行し、その後 traceway profiles list / traceway profiles use work を実行します。

4. プロジェクトを選択してスモークチェックする

traceway projects list
traceway projects use <project-id>
traceway exceptions list --since 24h

選択したプロジェクトは、以降のすべてのコマンドで暗黙的に使用されます。

フロー：デバッグ

/traceway debug issue X または /traceway debug <自由形式のバグの説明>。

1. イシュー参照を解決する

X はいくつかの形式を取ります。例外ハッシュ（16 桁の 16 進数）に解決してください。

参照の形式	解決方法
ダッシュボード URL	上記の「ダッシュボード URL の解決」を参照してください。/issues/... URL の場合、/issues/ の直後にあるパスセグメントがハッシュで、?preset／?from／?to が時間範囲を示します。URL がイシューを指している場合は、そのイシューの LAST（最新）の発生を修正してください。手順 2 を参照してください。
16 桁の 16 進数のみ	すでにハッシュです
その他（タイトル、エラーメッセージ、種類、ファイル名）	検索します：traceway exceptions list --since 7d --search "<text>"。結果が空の場合は、--since 30d（および --include-archived）に範囲を広げます
イシュー参照がなく、バグの説明のみ	下記のトリアージに進みます

検索で複数のグループが返された場合は、候補の一覧（ハッシュ、件数、最終確認日時、スタックの最初の行）を示し、詳細を調べる前にユーザーにどれを選ぶか尋ねてください。

traceway exceptions list --since 7d --search "checkout" --output json \
  | jq '.data[]? | {hash: .exceptionHash, count, lastSeen, top: (.stackTrace | split("\n")[0])}'

2. イシューを詳しく調べる

traceway exceptions show <hash> --page-size 5

これは最も価値の高い呼び出しです。完全なスタックトレース、recordedAt と attributes（ユーザー ID、アプリのバージョン、リクエストのコンテキスト）を含む発生一覧、および発生ごとの任意の traceId／spanId／sessionId が得られます。発生は新しいものから順に並び、それぞれに完全なスタックトレースが含まれるため、デフォルトの 50 件のページは 100,000 文字を大きく超え、ツールの出力上限で途中で切れてしまいます。--page-size 5 を指定すると、グループヘッダーと最新の 5 件の発生に絞られます。最初に読むにはこれで十分です。以下のように JSON を jq にパイプして絞り込む場合に限り、デフォルトのページを使用してください。traceId は OpenTelemetry のトレース ID（32 桁の 16 進数）で、リクエストのログやスパンに付与されるものと同じ ID です。レスポンスには relatedEntity も含まれます。これは最新の発生が起きたエンドポイント、タスク、または AI トレースであり、endpoints show／tasks show／ai-traces show に渡せる id と recordedAt が含まれています。firstSeen はデプロイとの関連付けに役立ちます。リリース直後に初めて現れたグループなら、そのリリースの差分が原因の手がかりになります。無効なハッシュを指定すると、not_found とともに終了コード 5 が返されます。その場合は検索に切り替えてください。

ユーザーがイシュー URL（またはハッシュ）を提示した場合は、「グループ」ではなく LAST の発生を修正してください。 1 つのハッシュに、複数の異なるエラーがまとめられていることがあります。ハッシュはメッセージを除去した正規化済みスタックトレースから計算されるため、スタックの先頭部分を共有する無関係な 2 つの障害（たとえば、どちらも同じミドルウェア／リカバリーフレームで捕捉された場合）が、1 つのグループにまとめられます。グループの代表スタックトレースや firstSeen は、ユーザーが見ているものとは異なる、すでに発生しなくなったエラーに属している可能性があります。最新の発生を基準にし、その特定の障害経路を修正してください。

# The occurrence the user actually wants: the latest one. Pin its exact message + attributes + trace.
traceway exceptions show <hash> --output json \
  | jq '.occurrences | sort_by(.recordedAt) | last
        | {recordedAt, message: (.stackTrace | split("\n")[0]), attributes, traceId, spanId}'

# Then confirm whether the group is homogeneous or mixed — distinct first lines = distinct bugs:
traceway exceptions show <hash> --output json \
  | jq -r '[.occurrences[].stackTrace | split("\n")[0]] | group_by(.)
           | map("\(length)x \(.[0])") | .[]'

グループに複数のエラーが混在している場合は、最後の発生に含まれるエラーだけに修正範囲を絞ってください。レポートでは他のクラスターにも触れますが、依頼されない限り修正しないでください。再現して修正すべき障害は、グループの代表スタックではなく、最後の発生のメッセージと attributes によって定義されます。また、その発生の recordedAt は、以下の ID 指定による traces show／sessions show 検索に渡す時間の手がかりになります。

3. トリアージと相関分析（自由形式のバグ説明にも対応する入り口）

説明から症状、影響を受けるエンドポイント／機能、時間範囲を抽出し、仮説を立てる前に複数のシグナルを確認します。

traceway exceptions list --since 24h --order-by lastSeen        # what is erroring (firstSeen for regressions, count for volume)
traceway logs query --since 24h --min-severity 17               # errors and worse
traceway logs query --since 24h --search "payment declined"     # search log bodies
traceway logs query --since 24h --service checkout-api --min-severity 13
traceway endpoints list --since 24h --search "checkout"         # latency p50/p95/p99, count and impact, --order-by impact|count|p95|lastSeen

重要度は名前ではなく OTel の数値です。1 は TRACE、5 は DEBUG、9 は INFO、13 は WARN、17 は ERROR、21 は FATAL です。フラグには --min-severity 17 を指定します。--severity error は指定しないでください。

トレースによる相関分析：発生事象やログ行にトレース ID が含まれている場合は、リクエスト全体のタイムラインを取得します。これは通常、根本原因を特定する最短ルートです。

traceway exceptions show $HASH --output json | jq -r '.occurrences[0].traceId' \
  | xargs -I{} traceway logs query --trace-id {} --output json

発生事象の recordedAt を必須の時間ヒントとして再利用し、パーティションの範囲内で両方の検索が行われるようにして、サービスをまたぐトレース全体とユーザーのセッションを取得します。

OCC=$(traceway exceptions show $HASH --output json | jq -c '.occurrences[0]')
TS=$(jq -r '.recordedAt' <<<"$OCC")
DT=$(jq -r '.traceId // empty' <<<"$OCC")
SID=$(jq -r '.sessionId // empty' <<<"$OCC")
[ -n "$DT" ]  && traceway traces show "$DT" --recorded-at "$TS"      # available endpoint/task/ai-trace/exception nodes across services
[ -n "$SID" ] && traceway sessions show "$SID" --started-at "$TS"    # the session + the exceptions that fired in it

traces show は、サービス間で利用可能なノードを接続します。各ノードの spanGraphStatus（テーブル出力の GRAPH 列）を確認してください。時間範囲、保持期間、読み取り上限によっては、スパンや関連する例外が欠落していることがあります。

システム全体の原因についてメトリクスを確認する（firstSeen と同時に発生する急増は、コードのバグではなく飽和状態を示唆します）。

traceway metrics query --name system.cpu.utilization --tag state=idle --aggregation min --since 24h   # busy = 1 - idle
traceway metrics query --name <name> --aggregation avg|sum|count|min|max [--tag key=value] [--group-by <tag>]

CLI では p50|p95|p99 も受け付けますが、サーバーにはメトリクスポイントの分位点集計機能がなく、黙って avg を計算します。これらをパーセンタイルとして提示しないでください。レイテンシのパーセンタイルは traceway endpoints list で取得でき、生のリクエスト所要時間から計算されます。metrics list はありません。存在しない名前を指定しても series: {} が正常に返されるため、名前を試しても問題ありません。Traceway OTel Agent のホストメトリクスは system.* という名前で保存され、OTLP ヒストグラムメトリクスは <name>.avg と <name>.count の 2 つの系列として保存されます。

4. コードとの相関分析

1. スタックトレースに記載されたファイルと行を開き、失敗した処理経路を読みます。
2. 問題の開始時刻が判明している場合は、その時点で何がリリースされたかを確認します。git log --since "<firstSeen>" --until "<firstSeen + 1h>" またはデプロイ履歴を確認してください。
3. 対象の発生事象における観測内容（メッセージ、影響を受けるエンドポイント、タイミング、量）全体を説明できる仮説を立てます。最初のスタックフレームだけを説明する仮説では不十分です。URL／ハッシュを手がかりに最後の発生事象を特定した場合（手順 2）は、そのエラーを説明してください。ハッシュを共有しているだけの兄弟クラスターまで、無理に 1 つの仮説で説明しようとしないでください。
4. ユーザーの指示に従って修正を提案または実装し、対象の発生事象における失敗経路に範囲を限定します。

5. 証拠が不十分なときは、推測せずに計測する

修正を書く前に、次の問いに正直に答えてください。テレメトリは実際にこの障害の原因を説明していますか？ 障害が発生した行、その行に届いた入力、そしてその入力が誤っていた理由を特定できれば、十分な証拠がそろっています。スタックトレースだけでは、通常不十分です。データによって裏付けられても否定されてもいない、もっともらしい説明も同様です。

説明できないなら、推測に基づく修正をリリースしないでください。挙動を変えるだけの推測では症状が隠れ、次の再現機会が失われ、さらにインシデント対応のサイクルが必要になります。代わりに、未解決の疑問に答えられる計測を追加し、次に発生したときに診断できるようにしてください。

特定の不足を埋めるシグナルを選びます。

特定できなかったこと	追加するもの
どの分岐が実行されたか、または入力値は何だったか	判断地点に、判断に使った値を属性として含めたログを追加します。障害経路では ERROR の重要度を使い、--min-severity 17 で検出できるようにします
どこで時間がかかったか、またはどのステップが失敗したか	疑わしい各ステップの周囲に、リクエストのアクティブなコンテキスト内で開始する子スパンを追加します
誰に、または何に起きたか（ユーザー、テナント、リリース、ペイロードの形状）	リクエストスパンに属性を追加するか、recordException に属性を渡します
どのくらいの頻度で発生するか、またはどの条件で発生するか	分析したいカーディナリティの低いディメンションをタグ付けしたカウンターまたはヒストグラムメトリクスを追加します
サービス境界のどこで問題が起きたか	呼び出しにトレースコンテキストの伝播を追加し、両側にスパンまたはログを追加します
そのコードパスが実行されているかどうか	エントリーポイントにログまたはカウンターを追加し、データがないこと自体を証拠にします

追加する際のルール：

• リクエストまたはタスクのアクティブなスパン内で出力します。これにより、トレース ID がログに付与され、トレース上に表示されます。
• 識別子はメッセージテキストではなく、必ず属性に入れます。グループ化の前にメッセージは除去されますが、属性はフィルタリングできます。
• カーディナリティを低く保ちます。ユーザー ID とリクエスト ID はスパン属性に入れ、メトリクスタグやスパン名には入れません。
• シークレット、トークン、個人データは決してログに記録しないでください。
• 一時的なデバッグ出力ではなく、恒久的な計測としてリリースします。明日削除するものでは何も分かりません。
• 対象領域に計測がまったくない場合は、ログを一行だけ追加するのではなく、まず traceway-setup スキルを使ってセットアップします。

その後、ユーザーに状況を説明して次につなげます。特定できなかったこと、追加したもの、再発時に実行する正確なコマンドを伝えます。

traceway logs query --trace-id <id> --output json
traceway exceptions show <hash> --output json | jq '.occurrences | last | .attributes'

計測の追加は、デバッグセッションの正当な成果であり、修正に失敗したということではありません。成果物として報告してください。

6. 報告して後片付けする

症状、証拠（例外ハッシュ、ログの抜粋、メトリクスの異常）、根本原因、修正内容を要約します。ユーザーが確認できるよう、traceway exceptions show <hash> の参照を含めます。修正のデプロイと検証が完了した後、アーカイブするのはユーザーから依頼があった場合に限ります。

traceway exceptions archive <hash> --yes

フロー：パフォーマンス

/traceway perf <endpoint or symptom>、または遅さ、高レイテンシ、p95/p99、「X が遅い理由」に関するリクエストに対応します。シニアパフォーマンスエンジニアとして、まず数値化し、コストが発生している箇所をスパンに特定し、チェックリストに照らして原因を確認し、コードの問題と飽和状態を切り分けてから、根本原因を特定します。読み取りのみを行い、アーカイブや変更は決して行いません。

完全な手法とボトルネックのチェックリスト（Select N+1、インデックス不足、頻繁な IPC、コネクションプールの枯渇、GC の一時停止など、さらに約 20 項目。それぞれについて、原因を確認する Traceway シグナルが記載されています）については、このスキルディレクトリの performance.md を参照してください（MCP 経由の場合は traceway://knowledge/performance リソース）。これが正式なリファレンスです。

このスキルに記載された読み取りコマンドを使った調査の流れ：

1. 定量化して局所化します。 traceway endpoints list --since 24h --order-by p95（または impact）を実行します。まずレイテンシの分布を確認します。p50がすでに高い場合、すべてのリクエストに影響しています（システム全体の問題：クエリ、インデックス、アルゴリズム）。p99がp50を大きく上回る場合は、テールの問題です（競合、プールの枯渇、GC、再試行、不安定な依存関係）。マークされた低速エンドポイントでは impact／impactReason がオフセット調整済みですが、生のp50／p95／p99は調整されていないことに注意してください。
2. 承認済みの基準値を確認します。 エンドポイントが遅いと判断する前に、traceway endpoints slow "<endpoint>" を実行します。offsetMs がゼロ以外の場合、オペレーターはその分のレイテンシを許容しています（reason に理由が示されています）。そのため、オフセットを超えたレイテンシだけが実際のリグレッションです。offsetMs 0 の場合は、デフォルトのしきい値が適用されます。システム全体で明らかな複数エンドポイントの低速化が起きている場合に限り、この手順を省略してください。
3. 開始時点を特定します。時間範囲を狭めてください。 デフォルトの時間範囲をそのまま調査するのではなく、発生開始時点を挟み込めるまで絞り込みます。traceway endpoints chart --metric-type p95 --interval-minutes <n> は、上位エンドポイントの時間経過に伴うレイテンシ（ms単位の {timestamp, endpoint, value}）を返します。各エンドポイントのバケットを順に確認し、p95が跳ね上がった最初のバケットを見つけてください。タイムスタンプはバケットの開始時刻なので、発生開始時点はそのバケット内にあり、それ以前ではありません。発生時刻を報告する前に、--from／--to を指定して該当バケットだけを再実行し、間隔を15分以下にしてください。traceway metrics query --name <metric> --interval-minutes <n> で原因を確認します（インフラ／ランタイムの推移）。上位5件に含まれない特定のルートについては、隣接する時間範囲で traceway endpoints list --search <name> --from <a> --to <b> を二分探索します。performance.md の「Pinpointing when the slowness started」を参照してください。
4. 代表的な低速トレースを取得します。 1つのリクエストのスパンウォーターフォールを確認するには traceway endpoints show <endpointId> --recorded-at <t> を、サービス横断のタイムラインを確認するには traceway traces show <traceId> --recorded-at <t>（endpoints show が出力する traceId）を使用します。先ほど特定した低速時間範囲内のトレースを選び、最も時間のかかっている箇所を見つけてください。
5. 最も時間のかかっている箇所をチェックリストに照らし合わせます。 支配的なスパンは、データベース呼び出し、外部呼び出し、プロセス内の計算、または処理開始前の空白（キュー待ち／ロック待ち／プールの枯渇）のどれでしょうか。performance.md で該当項目を確認してください。
6. コードの問題と飽和状態を切り分けます。 同じ時間範囲のインフラ／ランタイムメトリクスを取得します。まず traceway metrics query --name system.cpu.utilization --tag state=idle --aggregation min を実行します（使用率は1からアイドル率を引いた値です。このメトリクスは state ごとに分割されているため、必ずフィルターを指定してください）。続いて、state=used を指定した system.memory.utilization と、ランタイムのヒープおよびGCメトリクス（jvm.*、go.*、v8js.*）を確認します。レイテンシの発生開始時点と一致する急上昇は、コードのバグではなく飽和状態を示しています。
7. コードやデプロイと関連付けます。 手順3で特定した発生開始時刻を基に、その時点で何がリリースされたかを確認します。git log --since '<onset - 30m>' --until '<onset + 30m>' またはデプロイ履歴を確認してください。リリース時点で急増していればリグレッションです。デプロイがなく徐々に増加している場合は、データの増大（N+1、インデックスの欠落、ページネーションなし）が原因です。
8. 報告します。 ボトルネック、根拠（エンドポイントのパーセンタイル、発生開始時刻、支配的なスパン、関連するメトリクスの異常）、チェックリスト項目に対応付けた根本原因、具体的な修正方法を報告します。ユーザーが確認できるよう、endpoints show／traces show の参照情報も記載してください。エンドポイントが低速としてマークされている場合は、レイテンシが承認済みのオフセットを超えたかどうかも明記してください。

ウォーターフォールからコストの発生箇所を特定できない場合は、修正案を提示する前に中断してください。原因不明の空白、ハンドラー全体を覆う大きなスパン、または再現できないテールはいずれも、トレースの粒度が粗すぎて対応できないことを意味します。そのハンドラー内の疑わしい処理の前後に子スパンを追加し、次の低速リクエストで実際の原因が示されるのを待ってください。Debug flow の「When the evidence is not enough」を参照してください。

フロー：クエリ

自由形式のリクエスト（「本番環境で何か壊れていますか？」「/api/checkout は遅いですか？」「サービス X のエラーを表示してください」）には、読み取りコマンドを直接使用します。レイテンシや遅さに関するリクエストは、上記のパフォーマンスフローに振り分けます。

コマンドリファレンス

コマンド	目的
traceway projects {list,use}	アクティブなプロジェクトを一覧表示または選択します
traceway exceptions list	例外をグループ化して表示します。--search、--search-type text|regex、--order-by lastSeen|firstSeen|count、--include-archived
traceway exceptions show <hash>	1 つのグループを表示します：完全なスタックトレースと発生状況
traceway exceptions occurrence <id> --recorded-at <t>	ID で 1 つの発生を表示します（高速）：詳細全体、sessionId、記録
traceway logs query	ログを表示します。--search（--search-type body|attribute）、--service、--min-severity <n>、--trace-id
traceway endpoints list	エンドポイントごとの p50／p95／p99 と件数を表示します。--search、--order-by impact|count|p95|lastSeen
traceway endpoints chart	上位エンドポイントの経時的なレイテンシを表示します。--metric-type total_time|p50|p95|p99、--interval-minutes。レイテンシが変化した時点の特定に使用します
traceway endpoints slow <endpoint>	オペレーターがこのエンドポイントを低速とマークしたかどうかを表示します：{offsetMs, reason}。offsetMs 0 はマークされていないことを示します。オフセットは許容レイテンシのベースラインです
traceway endpoints show <id> --recorded-at <t>	ID で 1 つのリクエストを表示します：スパンのウォーターフォールと関連するエラー
traceway tasks show <id> --recorded-at <t>	ID で 1 回のバックグラウンドタスク実行を表示します
traceway ai-traces show <id> --recorded-at <t>	ID で 1 つの AI トレースと、その会話を表示します
traceway sessions show <id> --started-at <t>	ID で 1 つのセッションと、その中で発生した例外を表示します
traceway traces show <id> --recorded-at <t>	分散トレースを表示します：同じ ID を共有するすべてのサービスノード
traceway metrics query --name <metric>	時系列データを表示します。--aggregation、--tag、--group-by、--interval-minutes
traceway pages list / pages show <id>	オンコールページを表示します。--status active|open|acknowledged|resolved
traceway alerts list	アラートルールを表示します：種類、有効状態、スヌーズ解除時刻
traceway monitors list / monitors show <id>	アップタイムモニター、その状態、インシデントを表示します
traceway post-mortems list / post-mortems show <id>	ポストモーテム文書を表示します。--search、--tag
traceway profiles {list,use}, login, logout, version	プロファイルとセッションを管理します

ID を指定する show／occurrence コマンドには、ダッシュボードの URL、通知、または exceptions show の発生情報から取得した ID を使用します。また、記録のタイムスタンプ（--recorded-at／--started-at）が必須です。上記の「ID 指定による高速検索」を参照してください。

未実装です（フラグを捏造せず、ユーザーにウェブ UI を案内してください）：tasks／sessions／ai-traces／traces の list 動詞（これらには ID 指定の show のみ存在します）、および metrics list/discover。

レシピ

# What's broken right now
traceway exceptions list --since 1h --order-by lastSeen --page-size 10 --output json \
  | jq '.data[]? | {hash: .exceptionHash, count, lastSeen}'

# Did anything NEW break since a deploy at 13:00 UTC
traceway exceptions list --from 2026-06-11T13:00:00Z --to "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --order-by firstSeen --output json \
  | jq '.data[]? | select(.firstSeen >= "2026-06-11T13:00:00Z") | {hash: .exceptionHash, firstSeen, count}'

# Worst endpoint by latency
traceway endpoints list --since 1h --order-by p95 --page-size 1 --output json | jq '.data[0]'

# Errors for one service (exceptions --search is free text, not a service filter; use logs)
traceway logs query --service checkout-api --min-severity 17 --since 1h --output json \
  | jq '.data[]? | {timestamp, body, traceId}'

結果が空（data: null または data: []）でもエラーではありません。期間を広げ、アクティブなプロジェクトを再確認し（traceway projects list）、アプリが Traceway に一度も接続されていない場合は、まずセットアップしてください（traceway-setup スキル）。