cargo-diagnostics

Cargo CLI — 診断

ワークフローの挙動を調べるためのフォレンジック手順書です。1 回の実行を追跡し、複数の実行を調べてエラーを確認し、プレイのクレジット消費を分析します。このスキルは解釈レイヤーです。生データを取得する手段（run get、オーケストレーション SQL、請求メトリクス）は cargo-orchestration と cargo-billing に記載されています。ここでは各手順書で、どの手段をどの順序で使うか、また各出力形式が何を意味するかを説明します。

初期設定

すでにサインイン済みで（cargo-ai whoami がワークスペースを返す場合）、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

すべてのコマンドは標準出力に JSON を出力します。失敗時は {"errorMessage": "..."} を返して、ゼロ以外の終了コードで終了します。実行またはバッチを作成するコマンドはすべて非同期です。--wait-until-finished を渡すか、対応する get をポーリングしてください。クレジットの帰属を調べる手順（billing usage get-metrics、billing subscription get）には、管理者アクセス権のあるトークンが必要です。それ以外は標準トークンで利用できます。スキル一式をインストールすると、../cargo/references/prerequisites.md に CLI のバージョン固定、トークンのスコープ、管理者専用の機能が追加で記載されます。

どの手順書を使いますか？

What are you diagnosing?
│
├── One run / one record ("why did this record fail?",
│   "run succeeded but the output is wrong/empty")
│   └── references/run-trace.md
│
├── Many runs ("the batch has errors", "error rate spiked",
│   "which node keeps failing?")
│   └── references/batch-error-sweep.md
│
└── Cost ("this play is expensive", "where do the credits go?",
    "make this cheaper")
    └── references/play-optimize-credits.md

目安として、どの実行を調べるべきかまだ分からない場合は、まず一括調査から始めてください。最後に、トレースに渡せる代表的な実行 UUID が提示されます。

実行 UUID がまったく分からない場合（「最後の実行を見たい」「acme.com の実行」「エディターでプレイが何をしたか」など）は、references/run-trace.md § 0 を使って、症状から UUID を特定してください。なお、orchestration run list は --workflow-uuid を指定しない場合、--created-after と最大 30 日間の期間指定が必要です。そのため、このコマンドだけでは「最後の実行」を調べられません。一方、runs に対するオーケストレーション SQL ではフィルターは不要です。run list で拒否されたからといって、実行の入力と出力にアクセスできないと判断してはいけません。

cargo-analytics との境界： analytics は「エラー率は？」「バッチ結果をダウンロードして」「このセグメントをエクスポートして」のような、測定とエクスポートを担います。このスキルは「エラー率が上がった理由は？」「このレコードの出力が空なのはなぜ？」のような、原因の説明を担います。診断は、analytics のシグナル（エラー数の急増、バッチの failedRunsCount > 0 など）から始まり、analytics に戻って終わることがよくあります。原因を修正して実行し直した後の一括取得には、run download-outputs／batch download／segment download を使います。これらはすべて ../cargo-analytics/SKILL.md に記載されています。このスキルの証拠取得手段（run get、オーケストレーション SQL、請求メトリクス）は診断用であり、一括エクスポート用ではありません。

リファレンス

ドキュメント	内容
references/run-trace.md	UUID がない場合に、症状から実行を特定する方法（§ 0）。その後、ノードごとの実行、runContext の出力、分岐ルーティング、ノードごとのクレジットと実行時間を含め、最初から最後まで追跡します。
references/batch-error-sweep.md	バッチ／プレイ／ワークスペース全体からエラーのある実行を見つけ、根本原因ごとに失敗を分類し、代表例を選び、修正するか報告するかを判断します。
references/play-optimize-credits.md	ワークフローとノードにクレジット消費を帰属させ、優先順位に沿ってコスト削減策を適用します。実行料金は別途帰属させます（§ 2b）。これはノード実行 1 回あたり 0.01 クレジットで、creditsUsedCount には含まれないため、ノードごとの帰属では見落とされます。

すべての実行記録が利用する情報源

情報源	コマンド	確認できる内容
実行の詳細	cargo-ai orchestration run get <run-uuid>	run.executions[]（ノードごとのトレース）、runContext（nodeSlug をキーとするノードごとの出力）、runComputedConfigs（各ノードに実際に渡された設定）
トレース	cargo-ai orchestration trace list --started-after <iso> [--statuses error,degraded] [--workflow-uuid <uuid>] · trace count（同じフィルター） · trace get <trace-uuid>	トレースごとに1行を表示します。実行の系譜全体で1つのトリガーが引き起こしたすべての内容（ツールやエージェントの子実行、ホスト型ワーカーの呼び出し、チャットのアシスタントの応答ターン）です。status（pending／error／degraded／success）、rootRunUuid、rootRecordTitle、spansCount、failedSpansCount、creditsUsedCount、workerUuid、chatUuidを確認できます。--started-afterは必須です。trace getが返すのは集計結果のみで、スパンは含まれません
スパン	cargo-ai orchestration span list --execution-started-after <iso> [filters] · span count（同じフィルター。ただし--search／--limitを除く）	SQLを使わずにノードの実行内容を確認できます。フィルター：--batch-uuid、--run-uuid、--parent-run-uuid、--workflow-uuid、--execution-statuses pending,success,error、--node-action-slug、--node-integration-slug、--node-slug、--node-kind native|connector|tool|agent|worker、--execution-title-or-error-message <ilike>、--record-title-or-id、--search（listのみ：レコードのタイトル／ID、実行タイトルまたはエラー）。--execution-started-afterは必須です
オーケストレーション SQL	cargo-ai orchestration query execute "<sql>"	runs、batches、spans、recordsを対象に集計します（ClickHouse。スキーマプレフィックス不要。ワークスペース単位でスコープされます）。トレースのスパンをIDで一覧表示する唯一の方法：WHERE trace_uuid = '<uuid>'
請求メトリクス	cargo-ai billing usage get-metrics --from <date> --to <date>	クレジットの合計を確認できます。workflow_uuid、connector_uuid、agent_uuid、integration_slug、model_uuidでフィルターおよびグループ化できます
グラフの図	cargo-ai orchestration node diagram --run-uuid <uuid> --highlight <slug> --format ascii --raw	実行されたグラフと、失敗したノードを確認できます。無料で、実行は行われません

ルーティングのバグを説明する前に、グラフを表示してください。「誤った分岐に進んだ」 または「このステップが実行されなかった」という場合、図がその証拠になります。また、run getでは 分かりにくいon failureエッジも表示されます。スキップされたように見えるステップは、 実際にはfallbackChildUuidエッジを通じて実行が到達したステップであることがよくあります。 これは何も返さなかったのではなく、プロバイダーでエラーが発生したことを意味し、診断も 修正方法も異なります。フラグとASCII凡例については、../cargo-orchestration/references/node-diagram.mdを参照してください。

degradedはsuccessではありません。 ルート実行のノードでエラーが発生し、 fallbackOnFailure／フォールバックエッジによって実行が完了した場合、トレースはdegradedになります。 実行は成功と報告されますが、失敗したスパンはerrorのままです。errorは、ルート実行のノードで エラーが発生し、後続ノードがないために停止したことを意味します。子実行の失敗ではトレースの ステータスは決まりません。pendingは、どの深さであっても、実行中のスパンがあることを意味します。 --statuses error,degradedをまとめて確認してください。degradedのトレースは、グラフが吸収した プロバイダーの障害であり、通常はエラーと同じ根本原因によるものです。

クエリ構文、テーブルの列、上限については、../cargo-orchestration/references/examples/queries.mdを参照してください。デバッグに関するフィールドの意味については、../cargo-orchestration/references/troubleshooting.mdを参照してください。

調査結果の提示

../cargo/references/interaction.md に従ってください。結論（「20件の失敗のうち18件は、コネクターのトークンが期限切れという同じ原因によるものです」など）を最初に示し、証拠を短い表にまとめます。run get の生の JSON やクエリ結果全体を会話に貼り付けないでください。有料ノードを再実行する修正は、パイロットの承認プロセスを通す必要があります。まず10～20件のレコードを再実行し、実際のコストとヒット率を報告してから、残りの実行について、レコード数とクレジットの見積もりを明記してユーザーに承認を求めてください。原因を特定しただけでは、その原因を生んだバッチへの再課金の承認にはなりません。支出に関するルールの全文は、../cargo-gtm/references/cost-discipline.md を参照してください。

調査が行き詰まった場合

証拠が文書化された動作と食い違う場合（run get にフィールドがない、クエリの上限がドキュメントと一致しない、意味の通らないエラーが出るなど）は、報告を提出してください。これは公式な連絡経路であり、チームはすべての報告に目を通しています。

cargo-ai workspaceManagement report create \
  --title "<one-line summary>" \
  --description "<commands run, errorMessage verbatim, expected vs actual, UUIDs>"