mirror of https://github.com/getcargohq/cargo-skills.git synced 2026-09-14 19:17:15 +08:00

Files

T

Auree Aubert 92e24be8eb Document the analytics/diagnostics boundary; surface both in the README (#52 )

cargo-analytics and cargo-diagnostics overlapped on error handling with
no routing between them. This draws the line — analytics measures and
exports ("what happened"), diagnostics explains ("why") — and documents
it on every surface an agent might load first:

- cargo-analytics: new "Scope — measure and export, not explain"
  section with a question-shape routing table; the partial-batch-
  failures runbook now hands root-causing off to the batch-error-sweep
  runbook instead of duplicating it; frontmatter description routes
  "why did it fail" to diagnostics (bump 1.4.1 -> 1.4.2).
- cargo-diagnostics: mirror "Boundary with cargo-analytics" note —
  diagnoses start from an analytics signal and end back in analytics
  for bulk retrieval (bump 1.0.0 -> 1.0.1).
- cargo router: one reciprocal critical-rule line in each recap.
- README: capabilities table renamed to "Capabilities", the missing
  Diagnostics row added, and CDK + Diagnostics moved to the bottom as
  the two marked cross-cutting entries.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

2026-07-09 18:41:11 -07:00

3.9 KiB

Raw Permalink Blame History

Run analytics examples

Get metrics for a workflow

cargo-ai orchestration run get-metrics --workflow-uuid <uuid>

Response:

{
  "runMetrics": [
    {
      "nodeUuid": "node-uuid-1",
      "totalExecutionsCount": 1000,
      "successExecutionsCount": 950,
      "errorExecutionsCount": 30,
      "cancelledExecutionsCount": 5,
      "creditsUsedCount": 450
    }
  ]
}

Error rate per node = errorExecutionsCount / totalExecutionsCount. High error rate on a specific node means that step is failing.

Metrics scoped to a specific release

cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --release-uuid <release-uuid>

Metrics scoped to a specific batch

cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid>

Metrics for a date range

cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --created-after 2025-01-01 \
  --created-before 2025-01-31

Count errors

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

Response:

{ "count": 42 }

# Errors in a specific period
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-15 \
  --created-before 2025-01-16

# Errors in a specific batch
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error \
  --batch-uuid <batch-uuid>

Count finished runs

cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --is-finished

# In a date range
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --is-finished \
  --created-after 2025-01-01 \
  --created-before 2025-01-31

Count successful runs

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

Per-workflow cost analysis (full flow)

# 1. List workflows
cargo-ai orchestration workflow list

# 2. Get usage grouped by workflow
cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by workflow_uuid

# 3. Drill into a specific workflow
cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --workflow-uuid <uuid>

# 4. Get run-level metrics
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --created-after 2025-01-01 \
  --created-before 2025-01-31

Error monitoring and debugging (full flow)

# 1. Count errors
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error

# 2. Spot-check: count errors in the last 24 hours
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-15 \
  --created-before 2025-01-16

# 3. Download error runs for inspection
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-15

# 4. Check per-node error rates
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid>
# → Compare errorExecutionsCount vs totalExecutionsCount per node
# → High error rate on a specific node = that step is failing

This flow ends at detection — you now know how many runs fail and which node is the hotspot. To explain why (group failures by root cause, trace exemplar runs through runContext), continue with the cargo-diagnostics skill: ../../../cargo-diagnostics/references/batch-error-sweep.md, then run-trace.md on the exemplars it hands back.

List runs with filters

# All runs for a workflow (paginated)
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --limit 20

# Only error runs
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --statuses error \
  --limit 10

# Runs from a specific batch
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid>

# Runs for a specific record
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --record-id <record-id>

3.9 KiB Raw Permalink Blame History