cargo-observability

Cargo CLI — 可观测性

告警。 告警是一个定时阈值检查。每次 cron 触发时，它都会测量一个范围（要监控的对象），将测量值与一个阈值（触发条件）进行比较；触发时，它会执行操作（每个操作各自作为一次运行），并记录一个事件。这是对 cargo-diagnostics 的主动补充：诊断会在你发现故障之后解释原因；告警则会在指标越过界限的那一刻通知你。

所有功能都属于同一个 CLI 域：

cargo-ai observability alert   …   # the alert CRUD + preview surface
cargo-ai observability event   …   # an alert's firing history

初始化

已经登录（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

每条命令都会向 stdout 输出 JSON；失败时以非零状态码退出，并返回 {"errorMessage": "..."}。任何会创建运行或批次的操作都是异步的——请传入 --wait-until-finished，或轮询对应的 get 命令。告警受 observability:read / observability:write 权限控制。如果创建／更新／移除操作返回权限错误，说明令牌缺少 observability:write 权限——请使用管理员令牌，或申请授予该权限（../cargo-workspace-management/SKILL.md）。安装完整技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定要求、令牌权限范围和仅限管理员使用的功能。

每个告警的三个组成部分

部分	标志	含义
范围	--scope <json>	测量什么——六种来源之一：spans、runs、records、orchestrationQuery、storageQuery、model。
阈值	--threshold <json>	何时触发——由 metric、operator（gte/lte）和 value 组成。可选指标取决于范围。
操作	--actions <json>	触发时执行什么——一个 Action[]（连接器／工具／Agent／原生节点），每项操作各自作为一次运行执行。此项可选；省略后，告警不会执行操作，你可以通过事件查看触发情况。

范围和阈值是配对使用的——只有能够生成某项指标的范围才能计算该指标（例如，errorRate 需要遥测数据，freshness 需要模型）。完整的兼容性矩阵、每项指标的含义和单位，以及所有范围筛选字段，都见 references/scopes-and-thresholds.md——首次编写 --scope/--threshold 配对时，请先阅读。

黄金法则：先运行 preview，再运行 create

alert preview 会立即评估范围和阈值，且不会执行操作或写入事件。它会返回告警将测量的值，以及该值是否触发告警——这样你就能根据实际情况校准阈值，而不是靠猜测；同时也能在将其设为定时任务之前，确认范围和阈值的配对有效。

cargo-ai observability alert preview \
  --scope '{"kind":"runs","workflowUuid":"<uuid>","statuses":["error"]}' \
  --threshold '{"metric":"errorRate","operator":"gte","value":10}' \
  --window-minutes 1440          # last 24h; default 60

• outcome: "computed" → { value, total, failed, isBreached }。根据 value 设置阈值。
• outcome: "empty" → 该时间窗口内没有可测量的数据（参见 references/alert-lifecycle.md 中关于空值与零值的规则）。
• outcome: "notComputed" → { errorMessage }。SQL 查询无效、模型已删除，或范围和阈值配对无效，都会返回此结果——请在创建告警前修复问题。

--window-minutes 只会设置遥测范围（spans/runs/records）的时间窗口。model 会按当前状态进行测量；查询范围则会在其 SQL 中自行设置时间窗口。

务必先运行 preview。 它免费，是正确设置阈值的唯一方法，也能在配对无效的情况下，避免创建一个每次触发都会写入 error 事件的定时任务。

命令

所有命令都会输出 JSON。读取操作需要带有 observability:read 权限的令牌；创建／更新／移除操作需要 observability:write 权限（管理员令牌同时具备两者；普通成员令牌可能不具备——参见上文的初始化部分）。

创建告警

cargo-ai observability alert create \
  --name "CRM sync error rate" \
  --description "Page when the HubSpot sync starts failing" \
  --cron "*/30 * * * *" \
  --scope '{"kind":"runs","workflowUuid":"<workflow-uuid>","statuses":["error"]}' \
  --threshold '{"metric":"errorRate","operator":"gte","value":10}' \
  --actions '[{"kind":"agent","agentUuid":"<agent-uuid>","config":{"message":"{{alert.name}} breached: {{event.value}}% errors. {{alert.url}}"}}]'

• --cron — 5 字段 cron 或 @every <interval>（例如 @every 30m），始终使用 UTC，频率最多每分钟一次。UI 预设的最短间隔为 30 分钟；只有确有理由时才设置更短间隔（每次触发都会扫描 ClickHouse，并可能启动付费运行）。
• --disabled — 创建时暂停（在执行 update --enabled true 前不会进行任何评估）。
• --folder <uuid> — 将其归入某个文件夹（来自 cargo-workspace-management）。
• --actions — 可选。省略则创建静默告警。每个条目都是一个已配置的操作：不同于完全不带 config 的 orchestration action execute，告警操作必须提供 config，模板化消息就写在其中。配置会根据触发上下文进行模板化（{{alert.*}}、{{event.*}}）——完整变量列表请参见 references/alert-lifecycle.md。创建时会验证每个操作的目标（agentUuid/toolUuid/connectorUuid）在工作区中存在。

列出、获取、更新、移除

cargo-ai observability alert list                      # all alerts, each with its lastEvent
cargo-ai observability alert get <uuid>                # one alert + its lastEvent

cargo-ai observability alert update --uuid <uuid> \
  --enabled false                                      # pause it (true/false — must be literal)
cargo-ai observability alert update --uuid <uuid> \
  --threshold '{"metric":"errorRate","operator":"gte","value":20}'   # raise the bar
cargo-ai observability alert update --uuid <uuid> \
  --description none                                    # "none" clears; --folder none unfiles

cargo-ai observability alert remove <uuid>

--enabled 严格校验：只接受字面值 true 或 false——传入 --enabled yes 会被拒绝，而不是静默地禁用告警。在 update 中，任何省略的标志都会保持不变；--description none / --folder none 是明确表示“清除”的写法。

检查触发历史

cargo-ai observability event list <alertUuid>          # latest evaluation events, newest first

每个事件都包含 status（healthy / unhealthy / error）、测量得到的 value、触发时 scope/threshold/actions 的快照（告警之后可能会更改）、runUuids（操作启动的运行——将其传给 cargo-diagnostics 或 orchestration run get）、评估时间窗口，以及 error 事件的 errorMessage。unhealthy = 超出阈值并已触发；error = 无法计算指标。

评估的实际工作方式

生命周期——cron 时间窗口和 ClickHouse 索引延迟、最多触发一次的保证（告警不会对同一批行重复触发；持续超出阈值的情况会在下一次检查时重新检测）、区分空窗口与真实零值的规则（这使 lte 成为失效检测开关），以及完整的 {{alert.*}}/{{event.*}} 模板上下文——均记录在 references/alert-lifecycle.md 中。若要将告警用于任何对时效敏感的场景，请先阅读该文档。

示例配方

references/examples/recipes.md — 可直接复制粘贴的起始示例：错误率分页告警、额度预算防护、p95 延迟监控、失效检测开关（count lte 0——在工作流停止运行时告警）、模型新鲜度 / 空模型告警，以及自定义 SQL 查询告警。

声明式替代方案：defineAlert（项目）

此技能提供的是命令式接口——一次性调用 cargo-ai observability alert …。若要将告警作为代码管理（纳入 git、可复现，并与所监控的工作流一同部署），请改用项目的 defineAlert 构建器——参见 ../cargo-project/SKILL.md 和路由器中的“声明式与命令式”。范围/阈值/操作模型相同，编写方式不同。

成本控制

告警的操作会启动真实运行——如果某项操作调用了付费连接器操作或 Agent，每次超出阈值都会再次计费。阈值设置不当且 cron 间隔过短，可能每次检查都会超出阈值（并产生费用）。有两项保护措施：

• 先预览，再设置合适的阈值，确保告警针对真正的异常触发，而不是正常波动。
• 如果操作节点调用了基于额度计费的提供商操作，请像对待任何定期运行的付费工作流一样处理：阅读该提供商在 ../cargo-gtm/provider-playbooks/ 中的操作指南（尤其是其重复使用章节），并遵守 ../cargo-gtm/references/cost-discipline.md 中的支出规则。优先选择成本低的通知操作（例如向 Slack 发帖的 Agent 或连接器通知），避免使用会扇出调用的操作。

当 CLI 出乎意料时

如果文档中记载的标志、范围字段或响应格式与实际观察到的情况不符（可能是修复已发布，也可能是文档过时），请重新刷新 CLI 和技能；如果仍然对不上，请提交报告——团队会阅读：

cargo-ai workspaceManagement report create \
  --title "<one-line summary>" \
  --description "<exact command(s), errorMessage verbatim, expected vs actual, UUIDs>"

呈现结果

遵循 ../cargo/references/interaction.md：先说明结果（“已创建告警；当 CRM 同步的错误率在 30 min 内达到 10% 时，将通知值班 Agent”），用简洁的表格概述告警或其事件，切勿将原始 alert get / event list JSON 直接贴到对话中。