cargo-observability

Cargo CLI — オブザーバビリティ

アラート。 アラートは、スケジュールに従ってしきい値をチェックする機能です。cron の実行ごとにスコープ（監視対象）を測定し、測定値をしきい値（違反条件）と比較します。しきい値を超えた場合はアクションを実行し、それぞれを個別の実行として処理し、イベントを記録します。これは cargo-diagnostics を使った診断を補完する、事前対応型の機能です。診断では、障害に気づいた後で原因を説明しますが、アラートは指標が基準を超えた瞬間に通知します。

すべての機能は、1 つの 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

すべてのコマンドは JSON を標準出力に出力します。失敗時は {"errorMessage": "..."} を返し、ゼロ以外の終了コードで終了します。実行またはバッチを作成するコマンドはすべて非同期です。--wait-until-finished を渡すか、対応する get をポーリングしてください。アラートの操作には observability:read／observability:write 権限が必要です。作成／更新／削除で権限エラーが返された場合、トークンに observability:write がありません。管理者トークンを使うか、権限を付与してもらってください（../cargo-workspace-management/SKILL.md）。完全なスキルバンドルをインストールすると、../cargo/references/prerequisites.md で CLI のバージョン指定、トークンのスコープ、管理者専用の機能について確認できます。

すべてのアラートを構成する 3 つの要素

要素	フラグ	内容
スコープ	--scope <json>	測定対象です。spans、runs、records、orchestrationQuery、storageQuery、model の 6 つのソースのいずれかです。
しきい値	--threshold <json>	違反と判定する条件です。metric、operator（gte／lte）、value で構成されます。選択できる指標はスコープによって異なります。
アクション	--actions <json>	しきい値に違反した場合の動作です。Action[]（コネクター／ツール／エージェント／ネイティブノード）を指定し、それぞれを個別の実行として処理します。省略可能です。省略するとアラートは通知せず、イベントから違反を確認できます。

スコープとしきい値は対応するペアです。指標は、その指標を生成できるスコープでのみ算出できます（例：errorRate の算出にはテレメトリが、freshness の算出にはモデルが必要です）。完全な互換性マトリクス、各指標の意味と単位、すべてのスコープフィルターフィールドについては、references/scopes-and-thresholds.md を参照してください。使ったことのない --scope／--threshold の組み合わせを指定する前に、必ず確認してください。

基本ルール：create の前に preview を実行する

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 内でウィンドウを指定します。

必ず最初にプレビューしてください。 無料で利用でき、しきい値を適切に設定する唯一の方法です。また、無効な組み合わせを事前に検出できるため、実行のたびに 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 で、実行頻度は最大でも 1 分に 1 回です。UI のプリセットは 30 分が最短です。それより短い間隔にするのは、理由がある場合に限ってください。実行のたびに ClickHouse をスキャンし、有料の実行が発生する可能性があります。
• --disabled — 一時停止した状態で作成します（update --enabled true を実行するまで評価されません）。
• --folder <uuid> — フォルダーに保存します（cargo-workspace-management から取得）。
• --actions — 任意です。通知を行わないアラートでは省略します。各エントリーは設定済みのアクションです。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 のインデックス作成の遅延、最大 1 回の発火保証（同じ行に対してアラートが再発火することはありません。継続中の条件抵触は次の実行時に再検出されます）、空のウィンドウと実際のゼロ値を区別するルールにより 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 とルーターの「宣言型と命令型」を参照してください。スコープ／しきい値／アクションのモデルは同じですが、作成方法が異なります。

コスト管理

アラートのアクションは実際の実行として発火します。有料コネクターアクションやエージェントを呼び出すアクションの場合、条件に抵触するたびに再度課金されます。cron の間隔が短すぎる状態でしきい値を適切に設定しないと、実行のたびに条件に抵触して課金される可能性があります。次の 2 つの対策を講じてください。

• プレビューでしきい値を調整し、通常の変動ではなく、実際の異常時に発火するようにします。
• アクションノードがクレジット制のプロバイダーアクションを呼び出す場合は、スケジュールされた有料ワークフローと同様に扱います。../cargo-gtm/provider-playbooks/ にある該当プロバイダーのプレイブック（特に 継続利用 のセクション）を読み、../cargo-gtm/references/cost-discipline.md の支出ルールに従ってください。広範囲にアクションを展開するものではなく、安価な通知アクション（Slack に投稿するエージェントやコネクター通知）を優先してください。

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 分間で 10% に達すると、オンコール担当エージェントに通知します」）、アラートまたはそのイベントを簡潔な表にまとめてください。alert get や event list の生の JSON を会話に貼り付けないでください。