Audit event schema

The JSON fields of each event variant in /var/lib/yoink/audit/events.jsonl.

Read as MarkdownEdit on GitHub

Each line in an audit log file is one JSON object: the envelope fields, and the fields of the variant that event names.

Envelope (every event)

field type notes
v int Schema version. Currently 1. It increases on backward-incompatible changes. Older readers can refuse newer lines.
event_id string UUIDv7 for each line. The merge view removes duplicates on this field. The TUI uses it as a stable row identifier.
origin string "operator" for a line in the log on the computer of the operator. "host" for a line in the log on the host. See Storage.
ts string RFC 3339 wall-clock time with millisecond precision (2026-05-01T15:42:01.317Z).
deploy_id string UUIDv7, one for each run. A lexicographic sort orders by start time.
actor string $USER@$HOSTNAME of the operator. ? replaces a part that yoink cannot resolve.
yoink_version string The yoink version of the operator.
git_sha string | null Short git SHA of the working directory of the operator at the time of the run. null when git gives no SHA, for example outside a git repo.
host string The host that the event applies to. Empty for origin: "operator" events that are not host-specific (for example, a RunStarted that goes to more than one host).
event string Discriminator: selects the variant below.

Envelope events

RunStarted

field type notes
command string up. A rollback also runs as up.
services array<string> Selected service names. Without --service, every service in the config.

RunFinished

field type notes
command string Same as RunStarted.command.
ok bool true on a clean reconcile. false if a host or a service failed.
error string | null The error message that the operator sees when ok=false.

LockAcquired, LockReleased

No additional fields. The time between the paired events is the hold time of the deploy lock on that host.

Per-service / per-container events

HookStarted, HookFinished

yoink writes the hook events to the operator log, with the origin "operator". yoink audit log --origin host does not show them.

field type
name string

PullStarted, PullFinished

field type
image string
tag string

NetworkReady

field type notes
network string Docker network name.
created bool true if yoink created the network on this run. false if the network already existed.

ContainerStarted

field type
service string
container string
spec_hash string
tag string

yoink started the container of a new replica. The healthcheck comes after this event.

HealthcheckHealthy

field type notes
service string
container string
attempts int The number of probes until the healthcheck passed.

ContainerCreated

The new replicas passed their healthchecks and yoink completed the swap. This event records that the deploy occurred. yoink writes one for each service on each host. container is the first replica.

field type
service string
container string
spec_hash string
tag string

AlreadyAtSpec

field type
service string
container string
spec_hash string

Every replica was already at the desired spec. yoink did no work.

OldContainerStopped, ContainerRemoved

field type
service string
container string

DeployFailed

A new replica did not pass its healthcheck. yoink removed every container that the failed attempt created for the service on that host, and no old container.

field type notes
service string
container string The replica that failed.
log_tail array<string> The last 30 stdout/stderr lines of the failed container. yoink captures them before it removes the container. If yoink cannot get the logs, the one entry is the reason.

RollbackStarted, RollbackFinished

field type notes
service string
target_tag (Started) string The tag that yoink restores.
ok (Finished) bool
error (Finished) string | null

ContainerPruned

field type notes
service string | null null when the container had no yoink.service label.
container string

SecretsRotated

field type notes
new_recipient string The new age1… public key. The old recipient is in the earlier secrets: block. A diff of the git history shows it.

FileUploaded

field type notes
service string The service that owns the mount.
sha256 string Content hash. It is a part of the file name under /var/lib/yoink/files/.
remote_path string Absolute path on the host.

WebhookFired

One for each outbound webhook call, success or failure. The origin is always "operator".

field type notes
name string The name: of the webhook in yoink.yaml.
ok bool true only on a 2xx response.
status int | null HTTP status code when a response arrived. null when the call did not get a status (DNS / TCP / TLS / timeout / template error).
error string | null The failure reason. See Webhooks: error values. null when ok=true.

Variants that yoink does not write

Readers accept these variants, but yoink writes none of them to a log file.

Variant Reason
PullFinished, ContainerRemoved, RollbackStarted, RollbackFinished, ContainerPruned, SecretsRotated, FileUploaded No command emits the event.

Forensic vs. progress

In the host log, yoink appends a forensic event over SSH immediately, so a kill -9 during a deploy does not lose it. A progress event goes into a buffer for its host. yoink flushes the buffer with the next forensic event for that host, and at the end of the run. In the operator log, yoink writes every event immediately.

Forensic Progress
RunStarted, RunFinished HookStarted
LockAcquired, LockReleased PullStarted, PullFinished
HookFinished NetworkReady
ContainerCreated, ContainerRemoved ContainerStarted
DeployFailed HealthcheckHealthy
RollbackStarted, RollbackFinished OldContainerStopped
ContainerPruned AlreadyAtSpec
SecretsRotated
FileUploaded
WebhookFired

Storage

The two files have the same line shape and different paths:

origin path who writes
operator $XDG_STATE_HOME/yoink/audit/events.jsonl (defaults to ~/.local/state/yoink/audit/) The yoink process of the operator, as a local file write. Holds RunStarted, RunFinished, HookStarted, HookFinished, and WebhookFired.
host /var/lib/yoink/audit/events.jsonl on each host The operator over SSH (cat >>). Permissions are 0640, and the owner is the SSH deploy user. Holds all other events.
  • Rotation: when an active file is larger than 5 MiB after a write, yoink renames it to events-<UTC-timestamp>.jsonl. The next write starts a new active file.
  • Retention: yoink does not enforce one. yoink audit gc --keep <DURATION> removes rotated files that are older than the duration (default 90d), only on hosts. It never removes the active file. A cron job can run it. Rotated files on the operator side accumulate until you remove them manually.

See also

Type a flag, a config field, or a task.