How to customize your Ansible logs

Logs are a critical part of a sysadmin's troubleshooting process. Logging becomes even more important as you move from manual processes toward automated infrastructure configuration. When you start your automation journey, you will likely run Ansible playbooks from the command-line interface (CLI), and play outputs will be easily visible in real time. However, you will quickly learn that you want to adjust this output or save it to a file for later review, especially when you begin running playbooks from cron jobs or other automation systems.

[ Download now: A system administrator's guide to IT automation. ]

This article covers the basics of Ansible logging on the control node. Ansible also performs logging on managed nodes, but this article focuses on the machine you are running Ansible from. I will show you how to change the default standard output logger, add additional metadata to your output, and log to a file.

Learn logging basics

Logging in Ansible is handled by special plugins called callbacks, which respond to events. For example, as tasks in a playbook return, a callback controls printing them to standard output. These callbacks can be changed and configured to provide different output formats or send playbook outputs to an external source, such as a logging system.

Callback plugins are enabled and configured using the Ansible configuration file or environment variables. You can see a full list of available callbacks by running ansible-doc -t callback -l from the CLI. In this article, I use an ansible.cfg file in the local directory and a very simple playbook to demonstrate different callback plugins:

$ cat playbook.yaml
---

- hosts: localhost
  gather_facts: false
  tasks:
    - name: Print a message
      ansible.builtin.debug:
        msg: Hello World!

    - name: Download a web page
      ansible.builtin.uri:
        url: https://www.redhat.com

[ Learn more: Ansible vs. Terraform, clarified ]

Change the default callback for standard output

When you run an Ansible playbook from the command line, you get messages printed to standard output (stdout). Ansible can only have a single callback responsible for handling stdout. The default callback is familiar to anyone who has run a playbook, but you can change this with the stdout_callback config directive:

$ cat ansible.cfg
[defaults]
nocows=true
stdout_callback=ansible.posix.json

I set the standard output callback in this example to use the JSON callback. This results in JSON output that can be parsed using tools such as jq:

There are several useful callbacks that I often use when running my Ansible playbooks from the command line:

• ansible.posix.json: Prints output in human and machine-readable JSON
• ansible.posix.skippy: Reduces the amount of output for skipped tasks
• community.general.yaml: Prints output in human- and machine-readable YAML

[ Learn more about automation. Download Ansible for DevOps. ]

Enable additional callbacks

While only one callback can handle stdout at a time, you can enable additional callbacks to perform other actions. For example, the following configuration enables the ansible.posix.profile_tasks and ansible.posix.timer callbacks. The profile_tasks callback summarizes task execution time at the end of the play, and the timer callback provides timestamps for each task. Finally, the community.general.yaml stdout callback provides task output in YAML format:

$ cat ansible.cfg
[defaults]
nocows=true
stdout_callback=community.general.yaml
callbacks_enabled=ansible.posix.profile_tasks, ansible.posix.timer 

Specifying a -v to the ansible-playbook command produces more verbose output that clearly shows the YAML format of stdout, along with the profiling and timing information:

Some callbacks may also support or require additional settings in your Ansible configuration file. For example, the community.general.mail plugin requires configuration parameters so that it can send email with failure information. You can view the specific configuration options for a plugin with the ansible-doc -t callback ${callback name} command.

Log to a file

Enhancing the appearance of stdout is very useful when running playbooks from the command line, but many sysadmins prefer having a text file for their logs. It's easy to process text files with command-line tools, save them for later review, and store them for auditing purposes. The log_path configuration file directive tells Ansible to log to a file on the control node.

In this example, Ansible is configured to log play output to ./ansible_log.txt. I also left the ansible.posix.profile_tasks callback enabled so that task profiling information will be printed to stdout and the log file:

$ cat ansible.cfg
[defaults]
nocows=true
log_path=./ansible_log.txt
callbacks_enabled=ansible.posix.profile_tasks

This configuration gives you the best of both worlds. You can easily view live Ansible output at the CLI, but you also have a log file that you can review or process later:

Wrap up

This article shows how you can customize Ansible logging to fit your needs. You learned how callback plugins can alter the output that Ansible prints to the screen and how to configure Ansible to output to a log file.

Ansible has a variety of logging plugins, and you can even write your own. By experimenting with all of Ansible's available logging configurations, you are guaranteed to find an appropriate logging approach for your environment.