Callback plugins and run output

Everything ansible-playbook prints — the PLAY banners, the TASK headers, the JSON blobs, the recap — is produced by a callback plugin. None of it is built into the engine, and all of it is configurable without touching a playbook.

That last clause is the operational point. Changing what a run reports is a configuration change, reversible, with no diff in any repository your change process governs.

The one-stdout rule

$ ansible-doc -t callback -l

ansible.builtin.default default Ansible screen output
ansible.builtin.junit   write playbook output to a JUnit file
ansible.builtin.minimal minimal Ansible screen output
ansible.builtin.oneline oneline Ansible screen output
ansible.builtin.tree    Save host events to files

Five, and they divide into two kinds:

One stdout callback, set by DEFAULT_STDOUT_CALLBACK. Its documentation states the rule directly: you can only have one at a time. default, minimal and oneline are stdout callbacks and choosing one replaces the others.

Any number of notification callbacks, listed in CALLBACKS_ENABLED. These do not own the screen; they write files, post to services, collect timings. junit and tree are these.

[defaults]
stdout_callback = default
callback_result_format = yaml
callbacks_enabled = ansible.posix.profile_tasks, ansible.builtin.junit

Or by environment variable, which is how you do it for one run without changing anything:

ANSIBLE_STDOUT_CALLBACK=minimal ansible-playbook -i inventory site.yml

The single highest-value change: result_format: yaml

The default output for structured data is JSON:

$ ansible-playbook -i inv.ini small.yml

TASK [Report a structure] ******************************************************
ok: [web01.example.com] => {
  "msg": {
      "ports": [
          80,
          443
      ],
      "service": "nginx"
  }
}

The same run with one environment variable:

$ ANSIBLE_CALLBACK_RESULT_FORMAT=yaml ansible-playbook -i inv.ini small.yml

TASK [Report a structure] ******************************************************
ok: [web01.example.com] =>
  msg:
      ports:
      - 80
      - 443
      service: nginx

Ten lines become six, and the saving grows with the size of the structure. On a --diff run, or anything printing a registered result, this is the difference between readable output and scrolling.

There is a companion option, pretty_results — ANSIBLE_CALLBACK_FORMAT_PRETTY — and its documentation carries a warning worth quoting, because it is the sort of thing that costs an hour:

When set to true and used with the yaml result format, this option will modify module responses in an attempt to produce a more human friendly output at the expense of correctness, and should not be relied upon to aid in writing variable manipulations or conditionals. For correctness, set this option to false or set result_format to json.

Machine-readable artefacts

junit — a test report for CI

$ ANSIBLE_CALLBACKS_ENABLED=ansible.builtin.junit JUNIT_OUTPUT_DIR=./out ansible-playbook -i inv.ini small.yml

$ ls ./out && head -6 ./out/*.xml

small-1786486982.0603883.xml
<?xml version="1.0" ?>
<testsuites disabled="0" errors="0" failures="0" tests="2" time="0.0187306404113769531250">
<testsuite disabled="0" errors="0" failures="0" name="small" skipped="0" tests="2" time="0.0187306404113769531250">
	<testcase classname="/home/opsuser/project/small.yml:5" name="[web01.example.com] Small run: Report a structure msg={'service': 'nginx', 'ports': [80, 443]}" time="0.0086882114410400390625">
		<system-out>{
  "changed": false,

Every CI system on earth renders JUnit XML, so an Ansible run becomes a test report with per-task results and timings, for free, from an environment variable.

Note what is inside <system-out>: the full task result.

tree — one file per host

Writes each host’s results as JSON into a directory, which is the shape you want for per-host audit artefacts.

$ ANSIBLE_CALLBACKS_ENABLED=ansible.builtin.tree ANSIBLE_CALLBACK_TREE_DIR=./tree ansible-playbook -i inv.ini small.yml && ls ./tree

web01.example.com
web02.example.com

profile_tasks — where the time went

ansible.posix.profile_tasks prints a per-task duration and a summary of the slowest tasks. It is the first thing to reach for when a run that used to take eleven minutes takes forty.

It lives in the ansible.posix collection, so it is not present on a bare ansible-core controller — one more instance of Part XXVII’s theme, that the tool people assume is built in is a pinned dependency.

ANSIBLE_CALLBACKS_ENABLED=ansible.posix.profile_tasks \
ansible-playbook -i inventory site.yml

Part XXXIV covers performance work properly. The relevant discipline here is the general one: measure before tuning, and a callback is how you measure without changing the thing you are measuring.

Knowledge check