Skip to content
SHC Docs

Events

Every change the daemon sees becomes an event: a container starting, a deployment being installed, a node being lost, a replica being moved. shc events lists the newest ones and returns. The listing is bounded, so it always ends.

home01
$ shc events ls -n 5
...

Each line opens with the time and the node that reported the event, then a sentence, then the deployment it belongs to. shc events without ls is the same listing; -n bounds it and defaults to 100.

Cause two changes and read them back. A restart is an audit event and the docker events of the container it restarts; a protect is one audit event. The docker rows arrive within a few seconds of the restart.

home01
$ shc restart web
restarting deployment "web"
✔ restarted deployment "web"
$ shc protect placed
stack "placed" protected
home01
$ shc events ls -T audit,docker -s web -n 4
2026-10-09T06:58:28Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 stopped, deployment prod/web/prod
2026-10-09T06:58:28Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 exited with code 0, deployment prod/web/prod
2026-10-09T06:58:30Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 started, deployment prod/web/prod
2026-10-09T06:58:30Z home01 restarted stack web, deployment prod/web/prod, by shc

-T picks the event types. The default set is docker, audit and the four placement types; name one or several to narrow it. -s keeps the events of one deployment. -q hides the exec events docker raises for every healthcheck, which is most of the stream on a busy node.

home01
$ shc events ls -T docker -n 3
...
$ shc events ls -T audit -n 2
2026-10-11T02:45:57Z home01 restarted stack web, deployment prod/web/prod, by shc
2026-10-11T02:46:00Z home01 armed the destroy guard on stack placed, deployment prod/placed/prod, by shc
$ shc events ls -T placement_bind,placement_move,placement_move_cleared,placement_retire -n 3
...
$ shc events ls -s web -n 3
2026-10-11T02:45:55Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 exited with code 0, deployment prod/web/prod
2026-10-11T02:45:56Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 started, deployment prod/web/prod
2026-10-11T02:45:57Z home01 restarted stack web, deployment prod/web/prod, by shc
$ shc events ls -q -n 3
...

--node keeps the events one node reported. It takes the node’s name, or the id shc node info prints. Its docker rows depend on what the node’s containers did last, so read its audit rows: the two changes above are the newest home01 reported.

home01
$ shc node info home01
...
$ shc events ls --node home01 -T audit -n 2
2026-10-11T02:45:57Z home01 restarted stack web, deployment prod/web/prod, by shc
2026-10-11T02:46:00Z home01 armed the destroy guard on stack placed, deployment prod/placed/prod, by shc

-f follows instead of listing. It opens a stream and prints events as they happen, and it does not return on its own, so run it in a tmux session, cause an event from this shell and read the session’s screen. --since with -f replays everything newer than a sequence id before going live; 1 replays from the start of the window the daemon keeps.

home01
$ tmux new -d -x 200 -y 50 -s ev shc events -f -q --since 1
$ shc unprotect placed
stack "placed" unprotected
home01
$ tmux capture-pane -pt ev
...
2026-10-09T05:24:22Z home01 disarmed the destroy guard on stack placed, deployment prod/placed/prod, by shc
home01
$ tmux kill-session -t ev

--audit reads a different thing: the audit chain, the tamper-evident record of what was done and by whom. It is a table, filtered by the deployment with -s, by code with --event, by actor with --actor and by date with --since and --until. -a drops the deployment filter your context would add.

home01
$ shc events --audit -n 3
CREATED AT CODE ACTOR STACK MESSAGE ID TENANT ENVIRONMENT
...
$ shc events --audit -s placed -n 2
CREATED AT CODE ACTOR STACK MESSAGE ID TENANT ENVIRONMENT
2026-10-11T02:46:21.788130215Z A200404STKUNP shc placed disarmed the destroy guard on stack placed 1b5020cd-136d-4e53-9621-08464ccb2425 prod prod
2026-10-11T02:46:00.083941739Z A200403STKPRO shc placed armed the destroy guard on stack placed e9252918-474a-4fc9-9efe-b390160558c6 prod prod
$ shc events --audit --event A200403STKPRO -n 1
CREATED AT CODE ACTOR STACK MESSAGE ID TENANT ENVIRONMENT
2026-10-11T02:46:00.083941739Z A200403STKPRO shc placed armed the destroy guard on stack placed e9252918-474a-4fc9-9efe-b390160558c6 prod prod
$ shc events --audit --actor shc -a -n 2
...
$ shc events --audit --since 2026-10-01 --until 2027-10-01 -n 2
...

The actor is shc here because every command on this ladder runs as the node’s root through the daemon’s socket. On a cluster with users signed in through Keycloak, the actor is the user.

An event can also leave the cluster as a notification. Two kinds of config row make one: a transport under notification.providers, named by you and typed webhook, email, ntfy, slack or discord, and a rule in notifications that names the event codes it watches and the transport that carries them. Write a webhook transport called ops and a rule that sends it the test event’s code.

home01
$ shc config set notification.providers.ops.type webhook
KEY VALUE SCOPE
notification.providers.ops.type webhook global
$ shc config set notification.providers.ops.url http://127.0.0.1:18099/hook
KEY VALUE SCOPE
notification.providers.ops.url http://127.0.0.1:18099/hook global
$ shc config set notifications '[{"name": "tell-ops", "provider": "ops", "on": ["V200700NTFSNT"]}]'
KEY SCOPE
notifications global
┌─ value ───────────────────────────────┐
│ NAME ON PROVIDER │
│ tell-ops V200700NTFSNT ops │
└───────────────────────────────────────┘
$ shc notification ls
NAME CHANNEL ON DESTINATION PROVIDER
tell-ops generic V200700NTFSNT http://127.0.0.1:18099/**** ops
backup-failed none X500473BKPNOA,X500474BKPSRQ,X500467BKPHKF nowhere to send: notification.providers.operator is not defined operator
backup-fire-dropped none X500204BKSCSK,X500205BKSCTO nowhere to send: notification.providers.operator is not defined operator
backup-unprotected none X500470BKPCOV,X500478BKPPRO,X200091BKPCOW nowhere to send: notification.providers.operator is not defined operator

shc notification ls lists each rule with the codes it watches and where it sends them, the path of the address hidden. Your rule comes first. The three after it ship with SHC and watch the backup failure codes: a run that left no archive, a scheduled run that was skipped or cancelled, and a deployment no backup protects. They send through a provider named operator, and until you define one they have nowhere to send. A rule of yours with one of their names replaces it. shc notification test sends a rule one event now, with the code, message and payload you give it. Nothing listens on port 18099 here, so the daemon answers with the receiver’s refusal; pointed at a real receiver, the same command delivers.

home01
$ shc notification test tell-ops --code V200700NTFSNT --message 'a test from learn' --payload '{"from": "learn"}'
shc: [X500701NTFSND] notification send failed webhook Post "http://127.0.0.1:18099/hook": dial tcp 127.0.0.1:18099: connect: connection refused

Remove the rule and the transport.

home01
$ shc config unset notifications
KEY SCOPE REMOVED
notifications global true
$ shc config unset notification.providers.ops.type
KEY SCOPE REMOVED
notification.providers.ops.type global true
$ shc config unset notification.providers.ops.url
KEY SCOPE REMOVED
notification.providers.ops.url global true
$ shc notification ls
NAME CHANNEL ON DESTINATION PROVIDER
backup-failed none X500473BKPNOA,X500474BKPSRQ,X500467BKPHKF nowhere to send: notification.providers.operator is not defined operator
backup-fire-dropped none X500204BKSCSK,X500205BKSCTO nowhere to send: notification.providers.operator is not defined operator
backup-unprotected none X500470BKPCOV,X500478BKPPRO,X200091BKPCOW nowhere to send: notification.providers.operator is not defined operator

The shipped rules stay. shc doctor says so at info while they have nowhere to send and names the two commands that give them somewhere. An info line does not fail the run.

home01
$ shc doctor run --category notification
[info] notification.operator_provider
info: the shipped notification rules backup-failed, backup-fire-dropped, backup-unprotected have nowhere to send, notification.providers.operator is not defined, so a failed, skipped or cancelled backup notifies nobody
shc config set notification.providers.operator.type webhook, then shc config set notification.providers.operator.url <the receiver's URL>
✔ ran 1 diagnosis, 0 passed, 1 info

This page left the cluster as it found it: placed is unprotected again and the notification rows you wrote are removed.

Next: Logs.