5.1 The record: events and chains
Included from Basic tier
After this you can: read the events feed, focus it with filters, follow a correlation chain, triage a failure in one command — and read an id out of the record for a change you ran.
Before you start — tick each one:
- Lesson 3.1 — Your first change (
opschain learn 3.1)
In the GUI: Activity first and Chains second on every node page; the Audit history entry under Governance searches the estate-wide trail, and the chains screen's Triage view classifies a failing chain.
Everything that happens in OpsChain leaves an event: a change starting, a step failing, a trigger firing, an operator overriding a maintenance window. Events are the estate's flight recorder — and because every one carries a correlation id, they assemble into chains: the causal cascade from a first cause to everything it set in motion. This lesson teaches reading the feed and following a cascade, and ends with the one skill the Academy checks: starting from a change you ran, read two ids out of the record and say what they are.
1. The events feed
opschain events --tail 5
WHEN ID TYPE NODE USER CORRELATION DETAIL
2026-10-12T08:00:54.150055Z 01a12f20-ff86-706d-b8e0-f58cc746791d api:changes:success /projects/demoenterprise/environments/preprod/assets/web - 01a12f1e-1639-7654-b80d-d4d5d704d032 -
2026-10-12T08:00:54.160158Z 01a12f20-ff90-75a8-b88b-504ad413c9cc api:steps:success /projects/demoenterprise/environments/preprod/assets/sap - 01a12f1e-1639-7654-b80d-d4d5d704d032 -
2026-10-12T08:00:54.160498Z 01a12f20-ff90-7699-aeac-7e5bd8a68430 api:steps:success /projects/demoenterprise - 01a12f1e-1639-7654-b80d-d4d5d704d032 -
2026-10-12T08:00:54.177170Z 01a12f20-ffa1-715c-9565-e40ca3405233 api:steps:success /projects/demoenterprise - 01a12f1e-1639-7654-b80d-d4d5d704d032 -
2026-10-12T08:00:54.177183Z 01a12f20-ffa1-7732-8a85-d7a57439c4b3 api:workflow_runs:success /projects/demoenterprise - 01a12f1e-1639-7654-b80d-d4d5d704d032 -
Event types are namespaced: api: for lifecycle (api:changes:create,
api:steps:error, api:workflow_runs:success, api:artifacts:create),
audit: for human decisions (approvals, cancellations, overrides),
warn:/error:/info: for operational notices — and your own custom
types (lesson 5.4). The NODE column places each event in the estate; the
DETAIL column carries the message (failure reasons, denial causes).
Mind the two id columns. ID is the event's own identity — what you
hand to triggers test --event (lesson 5.2) and to events show.
CORRELATION is the chain the event belongs to — what you hand to
chains show. They are not interchangeable, and section 6 makes you
read one of each.
2. Focus the feed
opschain events --errors --since 1h # only error:/warn:/*:error/*:system_error, last hour
opschain events --tail 20 # just the last 20, oldest first
opschain events --reverse # oldest first (latest at the bottom)
opschain events --watch # keep following new events until Ctrl-C
opschain events --wide # untruncated detail column
opschain events --filter node=*dev* # only rows whose NODE column matches (any column, '*' wildcards)
opschain events --type-search agent # only types containing the text
opschain events --errors --since 24h
WHEN ID TYPE NODE USER CORRELATION DETAIL
2026-10-11T18:28:18.435725Z 01a12c39-0b86-755b-9030-fc5715241229 warn:agent:halted /demoenterprise/agents/rb-helper - 01a12c39-0b86-755b-9030-fc5715241229 force shutting down emergency maintenance
2026-10-11T18:23:04.309852Z 01a12c34-4076-7b10-9e4d-3b8b1da7784a warn:agent:tunnel_denied /demoenterprise/agents/rb-helper - 01a12c34-4076-7b10-9e4d-3b8b1da7784a undeclared_capability
--errors --since 1h is the estate-wide triage entry point: when an
alarm names no particular run, start here, pick the row, and take its
CORRELATION id to section 4. --watch (optionally with --tail N to
show recent history first) turns the feed into a live tail during a
deploy or a drill; the GUI's feed rides the same stream. When the
question is "how much, trending which way" rather than "which row",
opschain events stats aggregates the feed by class, type and actor
over a window (admin credential; opschain docs cli/events-stats).
3. Chains: the cascade behind an id
Every change, workflow run and event carries a correlation_id — the id
of the chain's root. A change you create directly is its own root, so
its run id is its correlation id. Everything it causes — nested
changes, lifecycle events, trigger firings, the runs those create —
inherits the same id, one chain_depth deeper per hop.
opschain chains show 01a12f1e-1639-7654-b80d-d4d5d704d032
patch-infrastructure · initiated by opschain (user) · started 2026-10-12 07:57:43Z · 1 runs · 19 changes · 200 events · 3m11s
+0s patch-infrastructure @ /projects/demoenterprise success · 3m11s 01a12f1e-1639
[Parallel Shutdown Apps (Non-Production)]
+0s ├─ Stop SAP Application (Pre-Production): sap:stop:run @ …/environments/preprod/assets/sap [template SAP 1.5.0] success · 40s 01a12f1e-16f4
+0s ├─ Stop Web Application (Dev): web:stop @ …/environments/dev/assets/web [template Web 1.8.0] success · 30s 01a12f1e-17ea
[Parallel Shutdown DBs (Non-Production)]
+41s ├─ Stop Database (Dev): database:stop @ …/environments/dev/assets/database [template Database 1.8.0] success · 33s 01a12f1e-b84d
[Patch Infrastructure (Non-Production)]
+1m20s ├─ Patch Infrastructure (Non-Production): infrastructure:patch @ /projects/demoenterprise/assets/infrastructure [template Infrastructure 1.8.0] success · 32s 01a12f1f-4e79
[Parallel Startup Apps (Non-Production)]
+2m31s └─ Start SAP Application (Test): sap:start @ …/environments/test/assets/sap [template SAP 1.8.0] success · 30s 01a12f20-63fe
One line per object, chronological, with its status, duration and
+offset from the chain's start; objects group under the workflow stage
that spawned them. Lifecycle events fold into their object's row —
--full keeps every event as its own row, --errors-only narrows to
failures, --timing annotates each object's share of the wall clock,
--group-by env|asset|project|none regroups, and --wide prints full
ids and untrimmed paths. Hops your login cannot read render as redacted
stubs — the chain's shape stays honest without leaking content.
4. One-command triage
opschain chains triage <correlation-id> [--lines 40]
The digest itself is assembled by the server — the GUI's Triage view reads the same one, so the two can never disagree. On a healthy chain:
patch-infrastructure · initiated by opschain (user) · started 2026-10-12 07:57:43Z · 1 runs · 19 changes · 200 events · 3m11s
no failures, nothing handled, no retries — nothing to triage
Triage is an assessment, not just a failure digest: a chain that
finished green but only by absorbing trouble renders "green, with
caveats" — one ~ line per finding (an error handler that ran, a step
that succeeded only after retries, a firing deferred by a maintenance
window). On a broken chain, triage does the first fifteen minutes of
an incident for you: each failed object with its failure class
(pre_execution, error with the exit status, system_error,
timed_out, cancelled), the runner it executed on, and the last
--lines of each suspect's log, followed by ready-to-paste next actions
(opschain logs …, retry, cancel). --bundle exports the triaged chain
as one redacted tarball for LimePoint support (opschain docs cli/chains-triage).
5. Reading a cascade: the operator loop
The flow to internalise — alarm → chain → suspect → logs → action:
opschain events --errors --since 1h # 1. what went wrong, estate-wide
opschain chains triage <correlation-id> # 2. the cascade, suspects classified
opschain logs <run-id> --step <path> # 3. the failing step's full log
opschain runs retry <run-id> # 4. act (lesson 3.2)
Every rendered error in OpsChain carries its correlation id, so whatever surface an alarm reaches you on, it leads back to its chain.
6. Read an id out
Now the rehearsal. Run one more hello change against your environment
from lesson 3.1 and follow it to success, then read its trail from the
feed, narrowed to that node:
opschain runs create change acme/environments/dev --action hello --follow
opschain events --filter node=*dev* --tail 6
WHEN ID TYPE NODE USER CORRELATION DETAIL
2026-10-12T09:14:02.011402Z 01a14620-1a2b-7c3d-8e4f-5a6b7c8d9e0f api:changes:create /projects/acme/environments/dev alice 01a14620-1a2b-7c3d-8e4f-5a6b7c8d9e0f -
2026-10-12T09:14:03.204118Z 01a14620-1f00-7a11-9b22-3c4d5e6f7a8b api:steps:create /projects/acme/environments/dev alice 01a14620-1a2b-7c3d-8e4f-5a6b7c8d9e0f -
2026-10-12T09:14:06.930551Z 01a14620-2e55-7b60-8c71-9d8e7f6a5b4c api:steps:success /projects/acme/environments/dev alice 01a14620-1a2b-7c3d-8e4f-5a6b7c8d9e0f -
2026-10-12T09:14:06.941207Z 01a14620-2e60-7d82-a1b2-c3d4e5f6a7b8 api:changes:success /projects/acme/environments/dev alice 01a14620-1a2b-7c3d-8e4f-5a6b7c8d9e0f -
Read two things off those rows:
- The chain's correlation id — the CORRELATION column, the same
value on every row of the change. Because you created the change
directly, it is also the change's own id, and the
api:changes:createrow is the chain's root (its ID equals its CORRELATION). Here:01a14620-1a2b-7c3d-8e4f-5a6b7c8d9e0f. - The id of the success event — the ID column of the
api:changes:successrow, not the change id and not the correlation id. Here:01a14620-2e60-7d82-a1b2-c3d4e5f6a7b8.
Prove both to yourself with the two reads that take one id each:
opschain chains show 01a14620-1a2b-7c3d-8e4f-5a6b7c8d9e0f
opschain events show 01a14620-2e60-7d82-a1b2-c3d4e5f6a7b8
id: 01a14620-2e60-7d82-a1b2-c3d4e5f6a7b8
type: api:changes:success
node path: /projects/acme/environments/dev
user: alice
system: false
correlation id: 01a14620-1a2b-7c3d-8e4f-5a6b7c8d9e0f
chain depth: 0
events show prints an event's own id and the correlation id it
belongs to on adjacent lines — the two answers, side by side.
Check yourself
- For the change you just ran: what is the correlation id every event of its chain shares, and what is the id of its
api:changes:successevent? Say which column ofopschain eventseach came from. - Verified version:
opschain academyruns theread-the-recordexercise against this lesson — it asks you for exactly those two ids and checks them against the server's own record.
What you learned
- Every happening is a typed event (
api:,audit:,warn:, custom) with a node path, an event ID and a CORRELATION id — and those two ids answer different questions. opschain eventsis the feed;--errors --sincefor triage,--filter/--type-searchto narrow,--tail/--reversefor recency,--watchfor a live tail;events statsaggregates it.- A chain is everything one cause set in motion; a change you create is
its own root, so its id is its correlation id;
chains showrenders the cascade and redacts hops you cannot read. chains triageclassifies every failure, attributes runners and tails the suspect logs — alarm → chain → suspect → logs → action; a green chain digests to its caveats or an explicit nothing-to-triage.events show <id>prints an event's own id beside its correlation id — the "read an id out" move.
Next: lesson 5.2 — Triggers (opschain learn 5.2), or back to your track (opschain learn).