cargo-analytics

Cargo CLI — 分析

測定とエクスポート：実行メトリクスのモニタリング、実行結果とバッチ結果のダウンロード、セグメントデータのエクスポート。

JSON レスポンスの完全な構造については、references/response-shapes.md を参照してください。 よくあるエラーとその修正方法については、references/troubleshooting.md を参照してください。 実行メトリクスとエラーのモニタリングについては、references/examples/run-analytics.md を参照してください。 データのエクスポートとダウンロードの例については、references/examples/exports.md を参照してください。 請求、使用状況メトリクス、サブスクリプションについては、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 をポーリングしてください。スキル一式がインストールされている場合は、../cargo/references/prerequisites.md に CLI のバージョン指定、トークンスコープ、管理者専用の機能が記載されています。

スコープ — 測定とエクスポート。原因の説明は対象外

このスキルでは、メトリクス、件数、ダウンロード、エクスポートなど、**「何が起きたか」と「データをください」に答えます。質問が「なぜ」**に変わったら、つまり、なぜこの実行は失敗したのか、なぜ出力が間違っているか空なのか、どの根本原因がこれらのエラーを説明するのか、なぜこのプレイはこれほど高コストなのかを尋ねられた場合は、cargo-diagnostics スキルに切り替えてください。診断では、そのランブックを使って生の情報を順に確認し、原因を特定します。

質問の例	読み込むもの
「エラー率はどれくらいですか？」／「今週失敗した実行はいくつですか？」／「結果／セグメントをエクスポートして」	このスキル
「なぜこの実行は失敗したのですか？」／「実行は成功したのに、出力が間違っているようです」	cargo-diagnostics → references/run-trace.md
「このバッチでエラーが発生するのはなぜですか？失敗し続けているノードはどれで、原因は一つですか、それとも複数ですか？」	cargo-diagnostics → references/batch-error-sweep.md
「このプレイはなぜこれほど高コストなのですか？クレジットはどこに使われていますか？」	cargo-diagnostics → references/play-optimize-credits.md

2 つのスキルは自然に連携します。分析で検出し（エラー率の急上昇、バッチでの失敗報告）、診断で原因を説明し（20 件中 18 件の失敗に共通の根本原因があることを特定）、原因を修正して実行を再実行した後、分析でクリーンな結果を取得します。

まずリソースを見つける

ほとんどの分析コマンドには UUID が必要です。クエリの前に対象を見つけてください。

cargo-ai orchestration play list            # all plays (name, workflowUuid)
cargo-ai orchestration tool list            # all tools (name, workflowUuid)
cargo-ai orchestration workflow list        # all workflows (uuid only — no name)
cargo-ai ai agent list                     # all agents (uuid, name)
cargo-ai connection connector list          # all connectors (uuid, name, integrationSlug)
cargo-ai storage model list                # all models (uuid, name, slug)

クイックリファレンス

cargo-ai orchestration run get-metrics --workflow-uuid <uuid>
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished
cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai orchestration query execute "SELECT status, count() FROM runs GROUP BY status"
cargo-ai segmentation segment download --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

適切なコマンドの選び方：

• run get-metrics / run count — ワークフロー単位の、事前定義された集計です。すでに workflowUuid がある場合に最適です。
• orchestration query execute — ワークスペース全体（runs、batches、spans、records）を対象とするアドホック SQL です。ワークフロー横断の分析、ノードごとの内訳、時系列データに最適です。
• run download / run download-outputs — レコード単位の出力を取得します。
• segment download / storage query execute — ストレージデータ（Companies、Contacts、…）を扱います。

ワークフロー実行のメトリクス

ワークフロー実行の集計メトリクス（成功率／エラー率、ノードごとのクレジット数）。

# Metrics for a workflow
cargo-ai orchestration run get-metrics --workflow-uuid <uuid>

# Scoped to a release, batch, or date range
cargo-ai orchestration run get-metrics --workflow-uuid <uuid> --release-uuid <uuid>
cargo-ai orchestration run get-metrics --workflow-uuid <uuid> --batch-uuid <uuid>
cargo-ai orchestration run get-metrics --workflow-uuid <uuid> \
  --created-after <start-date> --created-before <end-date>

実行数

モニタリングに便利な、特定の条件に一致する実行数を数えます。

cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai orchestration run count --workflow-uuid <uuid> --is-finished \
  --created-after <start-date> --created-before <end-date>
cargo-ai orchestration run count --workflow-uuid <uuid> --batch-uuid <uuid>

次のオプションをサポートします：--statuses、--batch-uuid、--release-uuid、--is-finished、--created-after、--created-before、--record-id、--record-title。

ワークフロー横断の分析や、run count で取得できないデータ（ノードごとの失敗の内訳、p95 所要時間、時間経過に伴うエラー率）には、orchestration query execute を使用してください。詳細はアドホックな実行分析（orchestration query）セクションを参照してください。

アドホックな実行分析（orchestration query）

オーケストレーションのランタイムテーブルである runs、batches、spans、records に対して SQL を実行し、既存のメトリクスコマンドでは対応できない分析を行います。テーブルはスキーマプレフィックスなしで参照し、ワークスペースのスコープは自動的に適用されます。スキーマと制限については、cargo-orchestration/references/examples/queries.md を参照してください。

# Error rate across the workspace in the last day
cargo-ai orchestration query execute \
  "SELECT countIf(status='error') / count() AS error_rate FROM runs WHERE created_at > now() - INTERVAL 1 DAY"

# Failed runs per workflow this week
cargo-ai orchestration query execute \
  "SELECT workflow_uuid, count() AS errors FROM runs WHERE status='error' AND created_at > now() - INTERVAL 7 DAY GROUP BY workflow_uuid ORDER BY errors DESC"

# Per-node failure counts (last 24h)
cargo-ai orchestration query execute \
  "SELECT node_slug, count() AS failures FROM spans WHERE execution_status='error' AND execution_started_at > now() - INTERVAL 1 DAY GROUP BY node_slug ORDER BY failures DESC"

# Credit spend by workflow this month
cargo-ai orchestration query execute \
  "SELECT workflow_uuid, sum(credits_used_count) AS credits FROM batches WHERE created_at >= toStartOfMonth(now()) GROUP BY workflow_uuid ORDER BY credits DESC"

読み取り専用で、上限があります。実行時間は 30 秒、結果行数は 10 000 行、スキャン行数は 10 000 000 行です。行スキャン上限を超えないよう、created_at／execution_started_at の条件で絞り込んでください。

実行結果のダウンロード

用途に応じて、2 つの異なるコマンドから適切なものを選んでください。

run download — 実行ごとに 1 行、ノードごとに 1 列（gzip 圧縮 CSV）

{"url": "..."} を返します。これはgzip 圧縮 CSVへの署名付き URL です。各行は 1 つの実行を表し、_uuid、_workspace_uuid、_workflow_uuid、_record_id、_record_title、_created_at、_finished_at、_status、_error_message に続いて、ノードのスラッグごとに 1 列が並びます。

各ノード列に格納されるのは、その実行の title、つまり人が読めるように短縮された要約であり、ノードの出力ではありません。 このファイルには runContext も executions[] もありません。多くの実行にわたって、どのノードでどのレコードにエラーが発生したかを確認するステータスボードとして扱ってください。ノードが生成した内容の証拠としては決して使用しないでください。これは、cargo-diagnostics が他のすべての箇所で title に適用するのと同じルールです。

# Every run of a workflow
cargo-ai orchestration run download --workflow-uuid <uuid>

# Date range
cargo-ai orchestration run download --workflow-uuid <uuid> \
  --created-after <start-date> --created-before <end-date>

# Specific statuses (run statuses: idle, pending, running, success, error,
# cancelling, cancelled, skipped — NOT "finished"/"failed")
cargo-ai orchestration run download --workflow-uuid <uuid> --statuses success,error

# Every run that reached a terminal state. `--is-finished` is `finished_at IS
# NOT NULL`, which is wider than success+error: cancelled and skipped runs
# stamp finishedAt too, so don't substitute one for the other.
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished

# From a specific batch
cargo-ai orchestration run download --workflow-uuid <uuid> --batch-uuid <uuid>

run download-outputs — 実行ごとの入力と出力（署名付き URL 経由の CSV／JSON）

プラットフォームからアクションの結果を取得する標準的な方法です。 API の POST /v1/orchestration/runs/download-outputs に対応します。{"url": "..."} を返します。これは CSV（デフォルト）または JSON ファイルへの署名付き URL です。実行ごとに 1 行で、同じ _ プレフィックス付きの実行メタデータに加え、input（最初のノードの解決済み設定）と output（選択したノードのコンテキスト。--output-node-slug を省略した場合は最後に実行されたノード）が含まれます。

# --workflow-uuid is the only required flag
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --format json \
  --limit 20

# Pin the output node explicitly, and filter by batch
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --output-node-slug <slug> \
  --batch-uuid <uuid>

output-node-slug を確認するには、cargo-ai orchestration release get <release-uuid> を実行し、nodes[].slug を確認してください。通常、終端の出力ノードの名前は output または end です。--limit を指定しない場合、このファイルにはワークフローに一致するすべての実行が含まれるため、サンプルだけが必要な場合は --limit を指定してください。

実行ごとではなくレコードごとに取得する場合： cargo-ai orchestration record download-outputs は同じ --workflow-uuid／--output-node-slug を受け取り、レコードごとに 1 行を出力します。--limit と --offset でページ分割できます（CLI ≥ 1.0.90）。1 つのファイルに収まらない大きなデータセットをエクスポートするには、すべてを一度に要求するのではなく、固定サイズの範囲を順に取得します（--limit 1000 --offset 0、次に --offset 1000、…）。run download-outputs も同様に、実行を対象としてページ分割します。

複数の実行の完全な runContext を取得する

1 回の呼び出しでは取得できません。ノードごとの完全なコンテキストは実行ごとの S3 オブジェクトであり、これを読み込めるコマンドは orchestration run get <run-uuid> だけです。実行は一度に 1 つずつ処理します。上記 2 つのエクスポートは、データを投影したものです。download は複数の実行にわたるノードの title を返し、download-outputs は複数の実行にわたる最初のノードの入力と 1 つのノードの出力を返します。その間にあるすべての情報を得るには、../cargo-diagnostics/references/run-trace.md § 0 の探索手順で取得した UUID を使って、run get を繰り返し実行してください。

オーケストレーション SQL は、この用途の代替にはなりません。runs と spans にはステータス、タイミング、クレジットが含まれますが、ノードの入力／出力列はありません。

バッチ結果のダウンロード

cargo-ai orchestration batch download --uuid <batch-uuid> --output-node-slug <node-slug>

output-node-slug を確認するには、cargo-ai orchestration release get <release-uuid> を実行し（バッチからリリース UUID を取得してください）、nodes[].slug を確認してください。

バッチの部分的な失敗への対処

status: "success" のバッチでも、個々の実行が失敗している場合があります。結果を完全なものとして扱う前に、必ずバッチにエラーがないか確認してください。

ステップ 1 — バッチの概要を確認します：

cargo-ai orchestration batch get <batch-uuid>
# → .runsCount          = total records submitted
# → .executedRunsCount  = records that reached a terminal state (success or error)
# → .failedRunsCount    = records that errored

ステップ 2 — 失敗した実行の件数を確認し、ダウンロードします：

cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error

cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error

ステップ 3 — 原因を特定します。 失敗の「理由」を突き止める作業（根本原因ごとの失敗のグループ化、代表的な実行の選定、runContext の確認）は、cargo-diagnostics スキルの役割です。../cargo-diagnostics/references/batch-error-sweep.md を読み込み、バッチ UUID を渡してください。

ステップ 4 — 失敗したレコードのみを再実行します：

原因を特定し、根本的な問題（コネクタの認証情報、不正な入力データ、レート制限）を修正した後：

# Extract record IDs from the failed run download, then:
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"recordIds","modelUuid":"<model-uuid>","ids":["id1","id2","id3"]}'

ノード出力スラッグでフィルタリングする：

バッチから特定ノードの出力のみをダウンロードするには（例：実行全体ではなく、エンリッチメントノードのみ）：

# 1. Get the release UUID from the batch
cargo-ai orchestration batch get <batch-uuid>
# → .releaseUuid

# 2. Find the node slug
cargo-ai orchestration release get <release-uuid>
# → nodes[].slug

# 3. Download that node's output
cargo-ai orchestration batch download \
  --uuid <batch-uuid> \
  --output-node-slug <node-slug>

セグメントデータのエクスポート

フィルター JSON では conjonction を使用します（conjunction ではありません）。これは意図的なものです。フィルター構文の詳細については、cargo-orchestration スキルの references/filter-syntax.md を参照してください。

# Full export (all records)
cargo-ai segmentation segment download \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[]}'

# With sorting and limit
cargo-ai segmentation segment download \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[]}' \
  --sort '[{"columnSlug":"created_at","kind":"desc"}]' \
  --limit 1000

重要： segment download では --segment-uuid ではなく --model-uuid が必要です。segment list から modelUuid を取得してください。

エンリッチメントを含むライブのページ分割クエリには、cargo-orchestration スキルの segmentation segment fetch を使用してください。

ヘルプ

すべてのコマンドで --help を使用できます：

cargo-ai billing usage get-metrics --help
cargo-ai orchestration run download --help
cargo-ai segmentation segment download --help