Ansible Debug Module: Display Output During Playbook Execution

The Ansible debug module is a simple but powerful tool used to display output directly during playbook execution. It allows you to print custom messages or variable values, making it easier to understand what’s happening at different points in your playbook.

The debug module is useful for troubleshooting errors, confirming data transformation, or just ensuring that variables are being set correctly.

In this guide, I’ll show you how to use the debug module with practical examples.

Why Use the Debug Module in Ansible Playbooks?

There are many situations where the debug module is invaluable:

• Variable Inspection: When working with complex data, such as facts or registered variables, it’s essential to see what’s stored in them.
• Task Tracking: Debugging helps you ensure that tasks are running as expected. You can see the flow of execution and check task-specific data.
• Troubleshooting Failures: When tasks fail, using the debug module can help you gather critical information about the failure and resolve issues faster.

Basic Syntax of Ansible Debug Module

The syntax for using the Ansible debug module is very easy. Below is an example playbook that shows the basic usage of the msg parameter:

---
- name: Basic usage of the debug module
  hosts: localhost
  tasks:
    - name: Display a custom message
      debug:
        msg: "Hello, World!"

This playbook simply prints the message Hello, World! to the console when run. Let’s explore more advanced usage with practical examples.

Example 1: Debugging Variables in Ansible

One of the most common uses for the debug module is printing variables to check their values during playbook execution. Here’s how to display the contents of a variable.

---
- name: Debugging variables in Ansible
  hosts: localhost
  tasks:
    - name: Display the value of ansible_facts
      debug:
        var: ansible_facts

This playbook will print out the ansible_facts variable, which contains information about the target host such as its operating system, memory, and network details. The output will look something like this:

ok: [localhost] => {
    "ansible_facts": {
        "ansible_distribution": "Ubuntu",
        "ansible_os_family": "Debian",
        "ansible_kernel": "5.4.0-74-generic",
        ...
    }
}

Example 2: Debugging Complex Data Structures

In many cases, especially when working with lists or dictionaries, the debug output can get hard to read. Ansible provides the ability to print complex data structures cleanly using the debug module. Here’s how you can print a list of items in a structured manner:

---
- name: Debugging complex data structures
  hosts: localhost
  vars:
    my_list:
      - item1: "apple"
        quantity: 5
      - item1: "banana"
        quantity: 10
  tasks:
    - name: Display the contents of a list
      debug:
        var: my_list

The output will look like this:

ok: [localhost] => {
    "my_list": [
        {
            "item1": "apple",
            "quantity": 5
        },
        {
            "item1": "banana",
            "quantity": 10
        }
    ]
}

This format is easier to read and allows you to see the structure of your variables.

Example 3: Using Debug to Print Host-Specific Variables

When running playbooks on multiple hosts, it’s important to understand the differences in host-specific variables. The debug module can print out variables that differ across hosts. In this example, we’ll print the IP address of each host:

---
- name: Print host-specific variables
  hosts: all
  tasks:
    - name: Display IP address of each host
      debug:
        msg: "The IP address is {{ ansible_default_ipv4.address }}"

When this playbook runs, it will print the IP address of each host in the inventory:

ok: [host1] => {
    "msg": "The IP address is 192.168.1.10"
}
ok: [host2] => {
    "msg": "The IP address is 192.168.1.11"
}

Example 4: Debugging Registered Variables

When using the register keyword in Ansible, it’s common to inspect the result of the task by printing the registered variable. Here’s an example where we register the result of a shell command and then use the debug module to inspect it:

---
- name: Debugging registered variables
  hosts: localhost
  tasks:
    - name: Check disk usage
      shell: df -h
      register: disk_usage

    - name: Display disk usage
      debug:
        var: disk_usage

This will display the output of the df -h command with metadata about the task's execution:

ok: [localhost] => {
    "disk_usage": {
        "changed": true,
        "cmd": "df -h",
        "stdout": "Filesystem      Size  Used Avail Use% Mounted on\n/dev/sda1        50G  25G  25G  50% /",
        ...
    }
}

Example 5: Debugging Loops

You can also use the debug module to inspect variables inside loops. This is particularly useful when working with lists of items and you need to check values as the loop progresses.

---
- name: Debugging a loop in Ansible
  hosts: localhost
  vars:
    fruit_list:
      - "apple"
      - "banana"
      - "cherry"
  tasks:
    - name: Loop through the fruit list
      debug:
        msg: "Current item: {{ item }}"
      loop: "{{ fruit_list }}"

This will print the current item being processed by the loop:

ok: [localhost] => {
    "msg": "Current item: apple"
}
ok: [localhost] => {
    "msg": "Current item: banana"
}
ok: [localhost] => {
    "msg": "Current item: cherry"
}

Example 6: Debugging a Failed Task

Imagine you have a task that’s supposed to create a directory, but for some reason, it fails. You can use the debug module to print out the error message and the relevant variable values that might help identify the issue.

---
- name: Debugging a failed task
  hosts: localhost
  tasks:
    - name: Attempt to create a directory
      file:
        path: /test_directory
        state: directory
      register: result
      ignore_errors: yes

    - name: Display the error message if the task failed
      debug:
        var: result
      when: result.failed

This example checks if the task failed and then uses debug to display the output of the result variable, showing why the task didn’t succeed. You might see output like this:

ok: [localhost] => {
    "result": {
        "changed": false,
        "msg": "There was an error creating /test_directory",
        "failed": true
    }
}

Learn Ansible with our course!

Conclusion

In this guide, we explored how to use Ansible debug module to handle error with practical examples. This module can make troubleshooting, development, and playbook writing much easier.

By leveraging the ability to print custom messages, variables, and task results, you can track the flow of data and identify issues in your playbooks with ease.

Combine it with the dry run feature of Ansible, and you will have a good way to troubleshoot your playbooks.

There are many more useful modules in Ansible. You should learn more about them, too.