cargo-analytics

Cargo CLI — Analytics

測量與匯出：監控執行指標、下載執行與批次結果、匯出區段資料。

完整的 JSON 回應結構請參閱 references/response-shapes.md。
常見錯誤與解決方法請參閱 references/troubleshooting.md。
執行指標與錯誤監控範例請參閱 references/examples/run-analytics.md。
資料匯出與下載範例請參閱 references/examples/exports.md。
帳單、用量指標與訂閱請使用 cargo-billing 技能。

範圍 — 測量與匯出，而非解釋

此技能回答「發生了什麼事」與「給我資料」：指標、計數、下載、匯出。一旦問題變成「為什麼」——為什麼這個執行失敗、為什麼輸出錯誤或空白、哪個根本原因導致這些錯誤、為什麼這個 play 這麼貴——請切換到 cargo-diagnostics 技能；其 runbook 會將原始表面資訊依序診斷。

問題聽起來像…	載入
「錯誤率是多少？」/「這週有多少執行失敗？」/「匯出結果/區段」	此技能
「為什麼這個執行失敗？」/「執行成功但輸出看起來不對」	cargo-diagnostics → references/run-trace.md
「為什麼這個批次有錯誤？哪個節點一直失敗？是一個原因還是多個？」	cargo-diagnostics → references/batch-error-sweep.md
「為什麼這個 play 這麼貴？點數花在哪裡？」	cargo-diagnostics → references/play-optimize-credits.md

這兩個技能可以自然串接：analytics 偵測（錯誤率飆升、批次回報失敗），diagnostics 解釋（20 個失敗中有 18 個共享一個根本原因），然後 analytics 擷取修正原因並重新執行後的乾淨結果。

前置需求

安裝、登入（--oauth / --token）、JSON 輸出慣例與錯誤格式請參閱 ../cargo/references/prerequisites.md。在執行以下任何指令前，請先用 cargo-ai whoami 驗證工作階段。

先探索資源

大多數 analytics 指令需要 UUID。在查詢前先探索。

cargo-ai orchestration play list            # 所有 play（名稱, workflowUuid）
cargo-ai orchestration tool list            # 所有 tool（名稱, workflowUuid）
cargo-ai orchestration workflow list        # 所有 workflow（僅 uuid — 無名稱）
cargo-ai ai agent list                     # 所有 agent（uuid, 名稱）
cargo-ai connection connector list          # 所有 connector（uuid, 名稱, integrationSlug）
cargo-ai storage model list                # 所有 model（uuid, 名稱, 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 — 以 workflow 為範圍的預定義聚合。當你已經有 workflowUuid 時最適合。
• orchestration query execute — 對整個工作區（runs、batches、spans、records）執行臨時 SQL。最適合跨 workflow 分析、各節點細分與時間序列。
• run download / run download-outputs — 逐筆記錄的輸出擷取。
• segment download / storage query execute — 儲存資料（Companies、Contacts…）。

工作流程執行指標

工作流程執行的聚合指標（成功/錯誤率、各節點點數）。

# 某個工作流程的指標
cargo-ai orchestration run get-metrics --workflow-uuid <uuid>

# 限定版本、批次或日期範圍
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）

對編排執行時表格（runs、batches、spans、records）執行 SQL，以涵蓋預設指標指令未提供的分析。表格引用時無需架構前綴；工作區範圍自動套用。請參閱 cargo-orchestration/references/examples/queries.md 了解架構與限制。

# 過去一天整個工作區的錯誤率
cargo-ai orchestration query execute \
  "SELECT countIf(status='error') / count() AS error_rate FROM runs WHERE created_at > now() - INTERVAL 1 DAY"

# 本週各工作流程的失敗執行數
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"

# 各節點失敗次數（過去 24 小時）
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"

# 本月各工作流程的點數花費
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 條件縮小範圍，以保持在掃描行數上限內。

下載執行結果

兩個不同的指令 — 根據需求選擇正確的。

run download — 完整執行記錄（中繼資料 + 各節點 runContext）

傳回每個執行作為 JSON 物件，包含狀態、時間、執行與 runContext.<nodeSlug>（各節點輸出）。最適合除錯或需要完整執行歷史時。

# 所有已完成的執行
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished

# 日期範圍
cargo-ai orchestration run download --workflow-uuid <uuid> \
  --created-after <start-date> --created-before <end-date>

# 特定狀態
cargo-ai orchestration run download --workflow-uuid <uuid> --statuses success,error

# 來自特定批次
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": "..."} — 一個簽署 URL，指向僅包含輸出節點資料（含輸入/輸出上下文）的 CSV（預設）或 JSON 檔案。當你只需要結果時，比下載完整執行記錄更快且更省資源。

# 必要：--workflow-uuid + --output-node-slug
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --output-node-slug <slug> \
  --format json \
  --is-finished

# 依批次與狀態篩選
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --output-node-slug <slug> \
  --batch-uuid <uuid> \
  --statuses finished

要找到 output-node-slug：執行 cargo-ai orchestration release get <release-uuid> → 查看 nodes[].slug。終端輸出節點通常命名為 output 或 end。

下載批次結果

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          = 提交的記錄總數
# → .executedRunsCount  = 達到終端狀態（成功或錯誤）的記錄數
# → .failedRunsCount    = 發生錯誤的記錄數

步驟 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 — 僅重新執行失敗的記錄：

在診斷並修正根本問題（連接器憑證、錯誤輸入資料、速率限制）之後：

# 從失敗執行下載中提取記錄 ID，然後：
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"recordIds","recordIds":["id1","id2","id3"]}'

依節點輸出 slug 篩選：

若要僅下載批次中特定節點的輸出（例如僅擴充節點，而非完整執行）：

# 1. 從批次取得版本 UUID
cargo-ai orchestration batch get <batch-uuid>
# → .releaseUuid

# 2. 找到節點 slug
cargo-ai orchestration release get <release-uuid>
# → nodes[].slug

# 3. 下載該節點的輸出
cargo-ai orchestration batch download \
  --uuid <batch-uuid> \
  --output-node-slug <node-slug>

區段資料匯出

篩選 JSON 使用 conjonction（而非 conjunction）——這是故意的。完整篩選語法請參閱 cargo-orchestration 技能的 references/filter-syntax.md。

# 完整匯出（所有記錄）
cargo-ai segmentation segment download \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[]}'

# 含排序與限制
cargo-ai segmentation segment download \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[]}' \
  --sort '[{"columnSlug":"created_at","kind":"desc"}]' \
  --limit 1000

重要： segment download 需要 --model-uuid，而非 --segment-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