traceway-write

書き込みアクセス対応のTraceway

このスキルは、traceway-write CLI（または書き込み対応のMCPサーバー）を使用して、オンコールエンジニアが日常的に行う変更を実行します。問題のアーカイブ、ページへの応答と解決、アラートルールのスヌーズまたは切り替え、モニターの実行、ポストモーテムの作成、遅いエンドポイントのマークなどが含まれます。

変更の前後にTracewayの機能の仕組みを説明する場合（ページへの応答がエスカレーションに与える影響、スヌーズとルールの無効化の違い、モニターによるインシデントの作成方法など）は、traceway-learn スキルを使用してください。これは製品の完全なガイドです。MCPでは、同じガイドを traceway://knowledge/learn リソースとして利用できます。

純粋な調査（問題のデバッグ、レイテンシ分析）には、読み取り専用の traceway スキルに、より詳細な手順が用意されています。そのコマンドはここでも同じように機能します。traceway のすべての読み取りコマンドは、traceway-write にもあります。

traceway-write MCPサーバー（stdio traceway-write mcp、または https://<instance>/mcp/write）が接続されている場合は、シェルからコマンドを実行するよりも、そのツールを優先してください。そのリソースにはこのスキルのナレッジが含まれており、ツール名は以下の表に記載されています。

セットアップ

1. 書き込み対応CLIをインストールする

traceway-write は独自のログインを必要とする別個のバイナリです。そのため、読み取り専用の traceway インストールを後から書き込み対応にアップグレードすることはできません。

curl -fsSL https://cli.tracewayapp.com/install.sh | sh -s -- --write
traceway-write version

ビルド済みアーカイブはリリースページの cli/vX.Y.Z タグに traceway-write_<version>_<os>_<arch>.tar.gz として用意されています。ソースからビルドする場合：cd traceway/cli && go build -tags write -o bin/traceway-write ./cmd/traceway

2. 書き込みアクセスでログインする

ブラウザーでのログインはユーザー自身に実行してもらってください（Claude Codeでは ! traceway-write login --url https://<instance>）。承認ページには、ログイン時に読み取りと書き込みのアクセスが要求されることが表示されます。

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

ヘッドレス環境での代替手段：ユーザーに Read and write パーソナルアクセストークン（Account > Personal Access Tokens、プレフィックス tww_、有効期限は90日以内）を作成し、内容を表示せずに保存してもらいます。

printf '%s' "$TRACEWAY_WRITE_TOKEN" | traceway-write login --url https://<instance> --token-stdin

読み取りトークン（twp_）を traceway-write に保存しても、書き込みはできません。サーバーはすべての書き込みを「This credential is read-only」というメッセージで拒否します。

3. 組織によるオプトイン

組織のオーナーまたは管理者が Settings > Agent Access > Allow agent writes を有効にする必要があります。それまでは、書き込みに対して403「Agent write access is turned off for this organization」が返されます。この設定を回避しようとしてはいけません。有効にできる担当者をユーザーに伝えてください。

4. プロジェクトを選択する

traceway-write projects list
traceway-write projects use <project-id>

CLIの代わりにMCPを使用する

• ローカルstdio：claude mcp add traceway-write -- traceway-write mcp（traceway-write login を使用します）。
• リモート：HTTP MCPサーバーとして https://<instance>/mcp/write を追加します。クライアントがOAuthを実行し、同意ページで読み取りと書き込みのアクセスが求められます。通常の /mcp サーバーでは、書き込みトークンを使用していても書き込みツールは公開されません。

書き込みアクセスでの操作

書き込みアクセスを使うと、エージェントはオンコールエンジニアがインシデントの発生中および発生後に行う定型的な操作を実行できます。書き込みアクセスは3つのレベルでオプトインする必要があり、書き込みが実行されるにはすべてのレベルで許可されている必要があります。

1. 認証情報。 書き込みができるのは、書き込み用の認証情報だけです。tww_ 個人用アクセストークン、traceway-write login、または /mcp/write サーバーに接続された MCP クライアントが該当します。twp_ トークン、traceway login、および /mcp サーバーは、その人のロールにかかわらず読み取り専用です。
2. 組織。 管理者が Settings > Agent Access を有効にする必要があります。有効になるまでは、エージェントによるすべての書き込みが、理由を示す 403 エラーで拒否されます。
3. ユーザー。 書き込みは、認証情報を作成したユーザーのロールで、ダッシュボードと同じルールに従って実行されます。readonly メンバーの書き込みトークンでは、イシューのアーカイブ、アラートの変更、モニターの実行、ポストモーテムの編集はできません。書き込みは「Your role in this project is read-only」で始まる 403 エラーで拒否されます。projects list（list_projects）を実行すると、各プロジェクトでのユーザーのロールを確認できます。ページの確認と解決には書き込みロールは必要ないため、どのメンバーの書き込みトークンでも実行できます。

書き込み用の認証情報による組織内のすべての書き込みは、Agent Access が無効なために拒否された場合も含めて、ユーザー、認証情報、プロジェクト、結果とともに、組織のエージェントアクティビティログに記録されます。

エージェントが変更できる内容

操作	CLI（traceway-write）	MCP ツール	元に戻せるか
イシューをアーカイブまたはアーカイブ解除する	exceptions archive <hash>... / unarchive	archive_exceptions / unarchive_exceptions	はい
ページを確認する	pages ack <id>	acknowledge_page	いいえ。ただし、エスカレーションを停止するだけなので問題ありません
ページを解決する	pages resolve <id> [--archive-issue]	resolve_page	いいえ
アラートルールを有効または無効にする	alerts enable <id> / alerts disable <id>	set_notification_rule_enabled	はい
アラートルールを一時停止する	alerts snooze <id> --minutes N（0 で解除）	snooze_notification_rule	はい。自動的に期限切れになります
モニターを今すぐ実行する	monitors run <id>	run_check	元に戻す操作はありません
ポストモーテムを作成する	post-mortems create / update <id>	create_post_mortem / update_post_mortem	編集内容はアクティビティログに保存されます
エンドポイントを予想される低速状態としてマークする	endpoints mark-slow <endpoint> --offset-ms N --reason ...（0 で解除）	set_slow_endpoint	はい

その他のすべての操作（ルールやチャネルの作成、スケジュールやポリシーの編集、ステータスページや公開インシデント更新、メンバー、トークン、プロジェクト設定、あらゆる項目の削除）は、引き続きダッシュボードで行います。これらの操作経路では、エージェントの認証情報は拒否されます。

すべての書き込み操作に関するルール

• 依頼された場合のみ実行します。 調査、デバッグ、要約、「見ておいて」という依頼が、書き込み操作の許可を意味することはありません。変更を行うには、ユーザーからの依頼が必要です。
• 依頼の意図がユーザーの想定より広い可能性がある場合は、確認します。 書き込み操作の対象となる複数のレコードに、ユーザーが知らない可能性のある違い（まだ発生中である、原因が異なる、別のチームに属しているなど）がある場合は、各レコードを列挙し、違いを説明してから、何を変更するか確認します。対象から外れたレコードを残す場合も含め、自分で判断してはいけません。
• 実行前に伝えます。 操作、レコード、新しい値を示す1行を書きます：「ルール12（GET /api/search の Endpoint P95）を60分間スヌーズします。」CLI は TTY 上で確認を求めます。それ以外では --yes が必要です。MCP クライアントは独自の承認手順を実行します。
• 元に戻せる方法を優先します。 無効化するよりスヌーズします。問題がまだ続いている間は、解決するより確認済みにします。ページの対応が完了したか確信が持てない場合は、--archive-issue でページを解決するより、イシューをアーカイブします。
• 何を変更したか、元に戻す方法とあわせて報告します。
• 403 は回答として扱います。 それぞれの 403 はそのレベルを示すものであり、ポリシー上の判断です。再試行したり、認証情報を切り替えたり、別の経路を探したりしてはいけません。エラーの内容と、変更できる人をユーザーに伝えます。
  • 「この認証情報は読み取り専用です」：認証情報が読み取り専用です。ユーザーには書き込み権限のある認証情報（tww_ トークン、traceway-write login、または /mcp/write）が必要です。
  • 「エージェントの書き込みアクセスがオフになっています」：組織の管理者が Settings > Agent Access で有効にします。
  • 「このプロジェクトでのあなたのロールは読み取り専用です」：認証情報には書き込み権限がありますが、プロジェクトにおけるユーザーのロールが readonly です。別の認証情報を使っても解決しません。組織のオーナーまたは管理者は Settings > Team Members でロールを変更するか、自分で変更を行えます。

プレイブック

誰かにページが通知された場合

1. pages list（ステータス active）でページを見つけ、次に pages show <id> でルール、対象、通知された人を確認します。
2. 読み取りツールを使って調査します。イシューのページの場合、ページには例外ハッシュが含まれています。デバッグの手順に従います。
3. ユーザーが対応中だと伝えたら、pages ack <id> を実行します。全員へのエスカレーションが停止します。
4. 原因が修正され、確認できたら、pages resolve <id> を実行します。ユーザーがイシューのアーカイブも希望する場合に限り、--archive-issue を付けます。

既知のインシデント中にアラートが繰り返し発生している場合

1. alerts list でルール ID を見つけ、問題のアラートであることを確認します。
2. alerts snooze <id> --minutes 60（またはユーザーが指定した時間）を実行します。ルールはミュートされ、時間が経つと自動的に再開します。
3. スヌーズが終了する時刻をユーザーに伝えます。誰かが再び有効にするまでオフにしておくことをユーザーが希望する場合に限り、ルールを無効にします。

修正を確認する場合

1. 対象のモニターに対して monitors run <id> を実行します。
2. 約1回分の実行間隔を待ってから monitors show <id> を実行し、最新の実行結果と未解決のインシデントが解決したかどうかを確認します。
3. イシューの場合は exceptions show <hash> を実行し、デプロイより新しい発生がないことを確認します。修正済みであることにユーザーが同意した場合に限り、アーカイブします。

事後分析の作成

1. 読み取りツールで事実を集めます。monitors show でインシデントの発生期間、問題と最初および最後の発生時刻、ページと確認した担当者、遅いエンドポイント、失敗したリクエストのトレースを確認します。
2. 次のセクションを含むドキュメントを Markdown で作成します。Summary、Impact（対象者と影響の程度を数値で記載）、Timeline（UTC で、最初のシグナルから解決まで）、Root cause、Resolution、Follow-up actions（担当者が分かる場合は各項目に記載）。テレメトリまたはユーザーが確認した事実のみを記載し、未解決の疑問は未解決として明記します。
3. 草案をユーザーに提示します。承認を得てから作成します。post-mortems create --title "..." --content-file draft.md --tag <tag> --incident <id>
4. 後から編集する場合は、まず post-mortems show <id> を実行し、その後、全文を改訂した本文とともに post-mortems update <id> --content-file revised.md --expected-updated-at <updatedAt from that show> を実行します。その間に誰かが編集していた場合、更新は競合エラーで失敗します。もう一度表示してから変更を適用し直してください。誤ったインシデントとのリンクを解除するには --unlink-incident を指定します。

エンドポイントの遅さが仕様である場合

1. レイテンシを許容することをユーザーに確認し、その理由を聞きます。
2. endpoints list --search "<endpoint>" で現在の p95 を確認します。
3. endpoints mark-slow "<endpoint>" --offset-ms <a bit above p95> --reason "<why>"。生のパーセンタイル値は変わりません。Apdex と影響度では、オフセットまではペナルティの対象にならなくなります。

コマンドリファレンス

traceway のすべての読み取りコマンドは traceway-write でも実行できます（exceptions list|show|occurrence、logs query、endpoints list|chart|show|slow、tasks show、ai-traces show、sessions show、traces show、metrics query、pages list|show、alerts list、monitors list|show、post-mortems list|show）。書き込みコマンドは次のとおりです。

コマンド	MCP ツール	変更内容
traceway-write exceptions archive <hash>... [--yes]	archive_exceptions	問題をデフォルトの一覧に表示しないようにします
traceway-write exceptions unarchive <hash>... [--yes]	unarchive_exceptions	問題を再び表示します
traceway-write pages ack <id>	acknowledge_page	ページのエスカレーションを停止します
traceway-write pages resolve <id> [--archive-issue]	resolve_page	ページをクローズし、必要に応じて問題をアーカイブします
traceway-write alerts enable <id> / disable <id>	set_notification_rule_enabled	ルールを有効または無効にします
traceway-write alerts snooze <id> --minutes N	snooze_notification_rule	ルールを N 分間ミュートします。0 を指定すると解除されます
traceway-write monitors run <id>	run_check	モニターの実行をただちにキューに追加します
traceway-write post-mortems create --title T [--content-file F] [--tag X] [--incident N]	create_post_mortem	事後分析を新規作成します
traceway-write post-mortems update <id> [--title] [--content-file --expected-updated-at] [--tag] [--incident | --unlink-incident]	update_post_mortem	指定したフラグのみを編集します。本文を新しくする場合は、その本文の基準とした updatedAt が必要です
traceway-write endpoints mark-slow <endpoint> --offset-ms N --reason R	set_slow_endpoint	エンドポイントの許容レイテンシを設定します。0 を指定すると解除されます

すべての書き込みコマンドは、実行しようとしている内容を表示し、TTY では確認を求めます。スクリプトやエージェントでは、ユーザーがその変更を明示的に依頼した場合に限り、--yes を渡すか TRACEWAY_ASSUME_YES=1 を設定してください。出力、フラグ、終了コード、エラー形式は読み取り CLI と同じです。パイプに渡した場合は JSON を出力し、--fields で出力を絞り込めます。認証および権限エラーの終了コードは 4 です。

ダッシュボード 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=、または関連する発生イベントのrecordedAtを使ってください。）
2. すでに取得したリスト／グループ：exceptions showの各発生イベントにはrecordedAtが含まれています。ID とrecordedAtをセットで記録してから、詳細を確認してください。
3. 通知：以下を参照してください。

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

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

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

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