opschain chains triage

Included from Basic tier

opschain chains triage <correlation-id> [flags]

One-command triage of a cascade. It renders the chain's errors-only tree first (the same condensed view chains show restricts to failures), then the server's triage digest (GET /api/chains/{id}/triage) — the one digest implementation the GUI uses too:

• one ✗ block per failing hop: its kind and summary, the server's failure class, the runner it ran on, its place in the topology (project · environment · asset · node), and the tail of its log;
• each failing object's block ends with its full-log shortcut (↳ full log: opschain logs <id>);
• when more than one failure executed on the same runner, a ! line names it — suspect the runner before the actions;
• a closing next actions: list: a ready-made retry POST for each failed change, and the chains show invocation for the chain's uncondensed view.

Triage is an assessment, not only a failure digest: a chain that finished green but absorbed trouble renders green, with caveats — nothing failed, but this chain absorbed: followed by one ~ line per finding — an error_handled step (a failure absorbed by an error handler), a retry survivor (a step that succeeded only after automatic retries), a deferred or suppressed trigger firing. Caveats also render under failures. A chain with nothing at all prints no failures, nothing handled, no retries — nothing to triage.

-o json / -o yaml emit the digest document itself (assessment, failure class, attributed runner, failing hops with log tails, caveats) and skip the rendering.

The support bundle (--bundle)

--bundle exports the triaged chain as a support bundle — the export lives on the triage verb only ("why send a support bundle for a chain that has not been triaged?"). The server assembles it (GET /api/chains/{id}/support_bundle — the same collector behind the GUI's TriagePanel export, so every surface produces the same bundle): the triage digest as the lead document (triage.json), the chain spine (chain.json), each readable member run in full with its step audits (runs/…), aggregated logs (logs/…), correlated events (events.json), trigger firings with deferring maintenance windows (firings.json, maintenance.json) and the converged-properties snapshots the runs recorded (properties/…), under a bundle.json manifest declaring the redaction level and any RBAC-omitted members.

Redaction: ALL PII is redacted by default — usernames pseudonymised to consistent user-N, emails scrubbed, secret-shaped values masked to ******. --include-identities restores identities ONLY; secrets are never included under any flag combination. The bundle is valid on a green chain too — a suspicious-but-green chain exports its caveats.

--bundle alone writes the server-named tarball in the cwd; pass the path with = (--bundle=support.tar.gz) to choose the file. The summary line names the file, the chain, the member count and the redaction level.

Flags

Flag	Meaning
--lines <n>	Log tail lines per suspect (default 40).
--bundle[=<path>]	Export the chain's support bundle; without a path, a named tarball in the cwd.
--include-identities	Include identities (usernames, emails) in the bundle — the only redaction widening; secrets are never included. Requires --bundle.

Exit codes

Code	Meaning
0	Digest rendered — including the nothing-to-triage case — and, with --bundle, the bundle written. The exit code reports the triage, not the chain's outcome.
1	The lookup or export failed — e.g. triage lookup answered 404 Not Found, support bundle export answered 404 Not Found.
2	Usage error, including a missing server target or --include-identities without --bundle.

Named errors

• chains need a server target — pass --server <url> or 'opschain context use <name>' (local mode has no chains) — exit 2.
• --include-identities widens the support bundle's redaction — pass it with --bundle — exit 2.
• chain lookup answered <status> / triage lookup answered <status> / support bundle export answered <status> — any non-200 answer; exit 1.

Examples

opschain chains triage 01999a7e-0b2c-7d31-a0f4-3e8b2c1d9e77
opschain chains triage 01999a7e-0b2c-7d31-a0f4-3e8b2c1d9e77 --lines 100
opschain chains triage 01999a7e-0b2c-7d31-a0f4-3e8b2c1d9e77 --bundle
opschain chains triage 01999a7e-0b2c-7d31-a0f4-3e8b2c1d9e77 --bundle=support.tar.gz --include-identities

See also

• opschain docs cli/chains-show — the full cascade when the digest is not enough.
• opschain learn 5.1 — the guided events-and-chains triage flow.