Skip to main content
Mapagam

Debugging Playbooks

1. Using Debug Module

Parameter Description Example
msg Message to display msg: "Debugging playbook"
var Variable to display var: ansible_facts
verbosity Level of verbosity (0-4) verbosity: 2

Example: Displaying a Message

- name: Display debug message
  debug:
    msg: "Current task is running"

Example: Displaying Variable Value

- name: Show host facts
  debug:
    var: ansible_facts
Note: The debug module is useful for inspecting variables and understanding playbook execution flow.

2. Printing Variables

Variable Type Description
ansible_facts Dictionary Contains facts collected about the target host
hostvars Dictionary Contains variables for all hosts in the inventory
vars Dictionary Contains variables defined in the playbook or inventory

Example: Debugging Variables in a Playbook

- name: Print host variables
  debug:
    var: hostvars[inventory_hostname]

Example: Using the debug module to print a variable

- name: Print a specific variable
  debug:
    msg: "The value of my_var is {{ my_var }}"
Note: The debug module is useful for inspecting variable values during playbook execution.

3. Using Verbosity Levels

Level Description Command Flag
0 Normal output (default) -v
1 Verbose output -vv
2 More verbose output -vvv
3 Debug mode (most verbose) -vvvv

Example: Running a playbook with verbose output

ansible-playbook site.yml -vvv
Note: The verbosity levels can help in identifying issues during playbook execution by providing more detailed logs and output.

4. Enabling Debug Mode

Example: Using debug mode in a playbook

---
hosts: localhost
gather_facts: no
tasks:
  - name: Debug task
    debug:
      msg: <span class="hljs-string>Hello from Ansible</span>
Option Description Notes
ansible-playbook --debug Enables debug mode for playbook execution Useful for detailed output during troubleshooting
ansible-playbook -vvv Verbose mode (level 3) Shows more detailed output including task execution
ansible-playbook -vvvv Very verbose mode (level 4) Shows even more details including connection info
Note: The debug mode can be enabled using the --debug flag or through verbose flags like -vvv and -vvvv.

5. Checking Task Output

Example: Using debug module to display task output

- name: Display variable value
  debug:
    var: my_variable
Option Values Description
var variable_name Variable to display
msg message_text Custom message to display
verbosity 0-4 Level of verbosity (0 = silent, 4 = most verbose)
Note: Use verbosity to control output visibility in different verbosity levels.

Example: Debugging with custom message

- name: Show host info
  debug:
    msg: "Host {{ inventory_hostname }} has IP {{ ansible_host }}"

6. Using Playbook Debugger

Example: Using debug module in playbook

- name: Debug playbook variables
  hosts: localhost
  tasks:
    - name: Print variable value
      debug:
        var: my_variable
Option Values Description
var variable_name Name of the variable to debug
msg message_text Custom message to display
verbosity 0-4 Level of verbosity (0-4)
Note: The debug module is useful for inspecting variables during playbook execution.

Workflow: Using debug in Ansible Playbook

  1. Add debug task to playbook
  2. Set var or msg parameter
  3. Run playbook with ansible-playbook
  4. View output in console

7. Setting Breakpoints

Example: Using debug module with breakpoints

- name: Debug playbook with breakpoint
  hosts: all
  tasks:
    - name: Set breakpoint on variable
      debug:
        var: my_variable
      when: my_variable is defined

    - name: Continue execution
      debug:
        msg: "Continuing after breakpoint"
Option Values Description
debug var Variable to inspect at breakpoint
when condition Condition to trigger breakpoint
Note: Breakpoints are useful for inspecting variables during playbook execution without stopping the entire playbook.
Warning: Using debug tasks as breakpoints can slow down playbook execution if used excessively.

8. Inspecting Variables

Variable Type Description
hostvars Dictionary Contains all variables for a specific host
group_vars Dictionary Variables defined per group
host_groups List Lists all groups a host belongs to
ansible_facts Dictionary Facts gathered about the target host

Example: Debugging Variables with debug module

- name: Debug hostvars
  debug:
    var: hostvars[inventory_hostname]

Example: Print all facts

- name: Print ansible_facts
  debug:
    var: ansible_facts
Note: Use hostvars to inspect variables specific to a host in a multi-host playbook.
Warning: Avoid printing sensitive variables like passwords in debug output.

9. Checking Task Status

Option Values Notes
ansible.builtin.debug msg Display message during playbook execution
ansible.builtin.debug var Display variable value during playbook execution
ansible.builtin.debug verbosity Control verbosity level (0-4)

Example: Displaying Variable Value

- name: Display host facts
  ansible.builtin.debug:
    var: ansible_facts

Example: Conditional Debug Output

- name: Debug with verbosity
  ansible.builtin.debug:
    msg: "Task completed successfully"
    verbosity: 2
Note: Use verbosity to control how much debug output is shown based on the -v flag passed to ansible-playbook.

10. Continuing Execution

Example: Using --step to debug playbooks

ansible-playbook debug.yml --step
Option Description Usage
--step Execute playbooks in step mode, pausing after each task to allow inspection Run with ansible-playbook command
--start-at-task Start playbook execution at a specific task Use with ansible-playbook to skip earlier tasks
Note: The --step option is useful for understanding how tasks are executed and identifying where errors occur.
Warning: Using --step in automated environments may cause delays or timeouts.

Workflow: Debugging with Step Mode

  1. Run playbook with --step flag
  2. Review output for task execution details
  3. Press Enter to continue to next task or q to quit
  4. Use --start-at-task to resume from a specific task

11. Logging Output

Option Values Description
ansible_log_path ~/ansible.log Path to the log file where Ansible will write logs.
ansible_log_appender file Appender to use for logging. Options: file, syslog, console.
ansible_log_file_mode 0600 File permissions for the log file.

Example: Setting up logging in ansible.cfg

[defaults]
log_path = /var/log/ansible.log
log_appender = file
log_file_mode = 0600
Note: Ensure the directory for log_path exists and is writable by the user running Ansible.
Log Level Description Usage
DEBUG Detailed information, typically of interest only when diagnosing problems. Use for detailed troubleshooting and development.
INFO Confirmation that things are working as expected. General operational messages.
WARNING Something unexpected happened, or something might go wrong in the future. For warnings that don't stop execution.
ERROR Due to a more serious problem, the software has not been able to perform some function. For errors that stop execution or cause failures.
CRITICAL A serious error, indicating that the program itself may be unable to continue running. For critical issues that halt execution.

Example: Using debug module to log output

- name: Log debug information
  debug:
    msg: "This is a debug message"
  verbosity: 2
Note: Verbosity levels can be controlled with the -vvv flags when running playbooks.

12. Using Assert Module

Parameter Description Example
assert Module to test a condition and fail if it's not met assert:
that List of conditions to test that: ['result.rc == 0']
fail_msg Message to display on failure fail_msg: 'Command failed'
success_msg Message to display on success success_msg: 'Command succeeded'

Example: Asserting Command Success

- name: Run a command and assert success
  command: /bin/echo "Hello World"
  register: result

- name: Assert that the command succeeded
  assert:
    that: ['result.rc == 0']
    fail_msg: 'Command failed'
    success_msg: 'Command succeeded'

Was this article helpful?

Related Cheat Sheets