ansible/docsite/rst/playbooks_debugger.rst
Kishin Yagami e4a6106ea5 Add debug strategy plugin (#15125)
* Add debug strategy plugin

* Fix Python 2-3 compatiblity issue

* Add document for debug strategy
2016-04-08 14:39:08 -04:00

159 lines
3.6 KiB
ReStructuredText

Playbook Debugger
=================
.. contents:: Topics
In 2.1 we added a ``debug`` strategy. This strategy enables you to invoke a debugger when a task is
failed, and check several info, such as the value of a variable. Also, it is possible to update module
arguments in the debugger, and run the failed task again with new arguments to consider how you
can fix an issue.
To use ``debug`` strategy, change ``strategy`` attribute like this::
- hosts: test
strategy: debug
tasks:
...
For example, run the playbook below::
- hosts: test
strategy: debug
gather_facts: no
vars:
var1: value1
tasks:
- name: wrong variable
ping: data={{ wrong_var }}
The debugger is invoked since *wrong_var* variable is undefined. Let's change the module's args,
and run the task again::
PLAY ***************************************************************************
TASK [wrong variable] **********************************************************
fatal: [192.168.1.1]: FAILED! => {"failed": true, "msg": "ERROR! 'wrong_var' is undefined"}
Debugger invoked
(debug) p result
{'msg': u"ERROR! 'wrong_var' is undefined", 'failed': True}
(debug) p task.args
{u'data': u'{{ wrong_var }}'}
(debug) task.args['data'] = '{{ var1 }}'
(debug) p task.args
{u'data': '{{ var1 }}'}
(debug) redo
ok: [192.168.1.1]
PLAY RECAP *********************************************************************
192.168.1.1 : ok=1 changed=0 unreachable=0 failed=0
This time, the task runs successfully!
.. _available_commands:
Available Commands
++++++++++++++++++
.. _p_command:
p *task/vars/host/result*
`````````````````````````
Print values used to execute a module::
(debug) p task
TASK: install package
(debug) p task.args
{u'name': u'{{ pkg_name }}'}
(debug) p vars
{u'ansible_all_ipv4_addresses': [u'192.168.1.1'],
u'ansible_architecture': u'x86_64',
...
}
(debug) p vars['pkg_name']
u'bash'
(debug) p host
192.168.1.1
(debug) p result
{'_ansible_no_log': False,
'changed': False,
u'failed': True,
...
u'msg': u"No package matching 'not_exist' is available"}
.. _update_args_command:
task.args[*key*] = *value*
``````````````````````````
Update module's argument.
If you run a playbook like this::
- hosts: test
strategy: debug
gather_facts: yes
vars:
pkg_name: not_exist
tasks:
- name: install package
apt: name={{ pkg_name }}
Debugger is invoked due to wrong package name, so let's fix the module's args::
(debug) p task.args
{u'name': u'{{ pkg_name }}'}
(debug) task.args['name'] = 'bash'
(debug) p task.args
{u'name': 'bash'}
(debug) redo
Then the task runs again with new args.
.. _update_vars_command:
vars[*key*] = *value*
`````````````````````
Update vars.
Let's use the same playbook above, but fix vars instead of args::
(debug) p vars['pkg_name']
u'not_exist'
(debug) vars['pkg_name'] = 'bash'
(debug) p vars['pkg_name']
'bash'
(debug) redo
Then the task runs again with new vars.
.. _redo_command:
r(edo)
``````
Run the task again.
.. _continue_command:
c(ontinue)
``````````
Just continue.
.. _quit_command:
q(uit)
``````
Quit from the debugger. The playbook execution is aborted.
.. seealso::
:doc:`playbooks`
An introduction to playbooks
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel