Run recordings
The file the volant.compat.record callback writes while ansible-playbook runs, line by line.
Before a team switches, it can record what ansible-playbook does on its real runs and have Volant replay those runs later. The volant.compat.record callback writes the recording. It ships in the volant.compat collection, needs only the Python standard library and runs on ansible-core 2.19 and later.
Enable it
Section titled “Enable it”volant compat install writes the volant.compat collection from the Volant binary, with no download.
Install the collection where ansible-core finds its collections, then add two sections to ansible.cfg:
[defaults]callbacks_enabled = volant.compat.record
[callback_volant_record]path = shadow/run-{{ timestamp }}.jsonl.gzThe callback is a notification callback. It never replaces the stdout callback, and the run’s output and exit code are the same as without it.
| Setting | Meaning |
|---|---|
path |
The file to write. {{ timestamp }} becomes the time the run started, in UTC, as 20261025T093000Z; no other template is read. A name ending in .gz is compressed with gzip. Missing parent directories are created with mode 0700. The default is shadow/run-{{ timestamp }}.jsonl.gz. |
VOLANT_RECORD_PATH sets path from the environment, which suits a CI job.
When the file cannot be written, the callback prints a warning and the run goes on without a recording.
Security
Section titled “Security”A recording holds task results as ansible-core saw them. It can contain decrypted vault values, the run’s extra variables and everything a module returned. Treat it as a secret:
- The file is created with mode
0600, and an existing file is set back to0600. - Keep the recording directory out of version control, and store recordings from CI as private artifacts with a short retention.
- A task with
no_logkeeps its status, and its result is recorded as{"censored": true}.
Format
Section titled “Format”A recording is JSON Lines: one JSON object per line, each with an event key. This page describes format 1.
event |
Fields |
|---|---|
header |
format, ansible_core (its version), cli (the run’s command line options, as ansible-core parsed them), cwd, playbooks (the path and sha256 of each playbook), inventory (sources as given, and the path and sha256 of each source that is a file), extra_vars_hash, started |
inventory |
hosts: every host of the inventory, with the groups it belongs to besides all |
play |
uuid, name, hosts (the play’s pattern) |
task |
uuid, path (file:line), name, action (the module or action’s full name), handler, role |
result |
host, task (its uuid), item, status, delegated_to, result |
retry |
host, task, attempt, result: one failed attempt of an until loop |
include |
file, hosts: a file include_tasks or include_role brought in, and the hosts that run it |
notify |
handler, host: a handler that will run on a host |
stats |
hosts (the recap of each host), custom (what set_stats gathered) |
The header and inventory lines come first, when the first play starts. stats is the last line of a complete run, so a recording without it comes from a run that was interrupted.
Notes on the fields:
- Every hash is SHA-256, in hexadecimal.
extra_vars_hashcovers each-eargument as given, followed by a NUL byte, and for an@fileargument the file’s content, followed by another NUL byte. A replay passes the same arguments, so the hash only changes when a file they name does. statusisok,changed,failed,skippedorunreachable. A failure thatignore_errorslet through is stillfailed.- In a loop, each item has a
resultline whoseitemis its index from 0. The line withitemset tonullthat follows is the whole task, with the items underresults. delegated_tois the host adelegate_tonamed, ornull.resultis the task’s result as callbacks receive it, including the keys ansible-core adds, such asinvocation,false_condition,skip_reasonandattempts. Which of those keys are present depends on the version: ansible-core 2.21 no longer passesinvocationto callbacks.- The result of fact gathering is recorded in full, because a replay renders templates with it. That is 50 to 100 KB per host, which is why gzip is the default.
include_tasksproduces ataskline and aresultper host of its own, then anincludeline per file.import_tasksproduces neither, only the imported tasks.notifylines are written when the handlers run, after the tasks that notified them.