Usage¶
Once ARA is installed and configured, you’re ready to use it!
Using the callback¶
The callback is executed by Ansible automatically once the path is set properly
in the callback_plugins Ansible configuration.
After running an Ansible playbook, the database will be created if it doesn’t exist and will be used automatically.
Using the ara_record module¶
ARA comes with a built-in Ansible module called ara_record.
This module can be used as an action for a task in your Ansible playbooks in order to register whatever you’d like in a key/value format, for example:
---
- name: Test playbook
hosts: localhost
tasks:
- name: Get git version of playbooks
command: git rev-parse HEAD
register: git_version
# Registering the result of an ara_record tasks is equivalent to
# doing an ara_read on the key
- name: Record git version
ara_record:
key: "git_version"
value: "{{ git_version.stdout }}"
register: version
- name: Print recorded data
debug:
msg: "{{ version.playbook_id}} - {{ version.key }}: {{ version.value }}
It also supports data types which will have an impact on how the value will be displayed in the web interface. The default type if not specified is “text”. Example usage:
---
- ara_record:
key: "{{ item.key }}"
value: "{{ item.value }}"
type: "{{ item.type }}"
with_items:
- { key: "log", value: "error", type: "text" }
- { key: "website", value: "http://domain.tld", type: "url" }
- { key: "data", value: '{ "key": "value" }', type: "json" }
- { key: "somelist", value: ['one', 'two'], type: "list" }
- { key: "somedict", value: {'key': 'value' }, type: "dict" }
It is also possible to run an ara_record task on a specific playbook that
might already be completed. This is particularly useful for recording data that
might only be available or computed after your playbook run has been completed:
---
# Write data to a specific (previously run) playbook
# (Retrieve playbook uuid's with 'ara playbook list')
- ara_record:
playbook: uuuu-iiii-dddd-0000
key: logs
value: "{{ lookup('file', '/var/log/ansible.log') }}"
type: text
Or as an ad-hoc command:
ansible localhost -m ara_record \
-a "playbook=uuuu-iiii-dddd-0000 key=logs value={{ lookup('file', '/var/log/ansible.log') }}"
This data will be recorded inside ARA’s database and associated with the particular playbook run that was executed.
You can then query ARA, either through the CLI or the web interface to see the recorded values.
Using the ara_read module¶
ARA comes with a built-in Ansible module called ara_read that can read data
that was previously recorded with ara_record within the same playbook run.
This module can be used as an action for a task anywhere in your in your Ansible playbooks as long as it is within the same playbook run. It can be re-used across plays or roles if necessary, for example:
---
- name: Test play on localhost
hosts: localhost
tasks:
- name: Compute md5sum of file
command: md5sum file
register: local_mdfive
- name: Record md5sum of dile
ara_record:
key: "md5sum"
value: "{{ local_mdfive.stdout }}"
- name: Test play on remote hosts
hosts: webservers
tasks:
- name: Retrieve md5sum
ara_read:
key: "md5sum"
register: mdfive
- name: Compare md5sum of files
shell: diff <(md5sum file) <(echo "{{ mdfive.value }}")
It is also possible to run an ara_read task on a specific playbook that
might already be completed. This is particularly useful for reading data that
might only be available or computed after your playbook run has been completed:
---
# Read data from a specific (previously run) playbook
# (Retrieve playbook uuid's with 'ara playbook list')
- ara_read:
playbook: uuuu-iiii-dddd-0000
key: logs
register: logs
Or as an ad-hoc command:
ansible localhost -m ara_read -a "playbook=uuuu-iiii-dddd-0000 key=logs"
Note
ara_read on a specific playbook id should only be used if you need to
tie data back into Ansible for other tasks.
If you just need to browse or view recorded data on the command line, you
should probably be using the ARA CLI: ara data show.
Looking at the data¶
Once you’ve run ansible-playbook at least once, the database will be populated with data:
# Example with sqlite
$ sqlite3 ~/.ara/ansible.sqlite
SQLite version 3.11.0 2016-02-15 17:29:24
Enter ".help" for usage hints.
sqlite> select * from playbooks;
15d05ac3-95b6-4767-ab1e-5365f76e5b09|playbooks/test.yml|2016-05-14 03:17:57.866103|2016-05-14 03:17:59.451822
# Example with MySQL
# mysql -e "select * from ara.playbooks;"
+--------------------------------------+--------------+---------------------+---------------------+
| id | path | time_start | time_end |
+--------------------------------------+--------------+---------------------+---------------------+
| 48912da8-4e83-4fdb-b73d-62b03f2a5ed9 | playbook.yml | 2016-05-14 03:27:39 | 2016-05-14 03:27:39 |
+--------------------------------------+--------------+---------------------+---------------------+
Querying the database with the CLI¶
ARA provides a CLI client to query the database.
Example commands:
$ ara help
usage: ara [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug]
A CLI client to query ARA databases
optional arguments:
--version show program's version number and exit
-v, --verbose Increase verbosity of output. Can be repeated.
-q, --quiet Suppress output except warnings and errors.
--log-file LOG_FILE Specify a file to log output. Disabled by default.
-h, --help Show help message and exit.
--debug Show tracebacks on errors.
Commands:
complete print bash completion command
data list Returns a list of recorded key/value pairs
data show Show details of a recorded key/value pair
file list Returns a list of files
file show Show details of a file
generate html Generates a static tree of the web application
generate junit Generate junit stream from ara data
help print detailed help for another command
host facts Show facts for a host
host list Returns a list of hosts
host show Show details of a host
play list Returns a list of plays
play show Show details of a play
playbook delete Delete playbooks from the database.
playbook list Returns a list of playbooks
playbook show Show details of a playbook
result list Returns a list of results
result show Show details of a result
stats list Returns a list of statistics
stats show Show details of a statistic
task list Returns a list of tasks
task show Show details of a task
# ara help result list
usage: ara result list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
[--max-width <integer>] [--noindent]
[--quote {all,minimal,none,nonnumeric}]
Returns a list of results
optional arguments:
-h, --help show this help message and exit
output formatters:
output formatter options
-f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated
table formatter:
--max-width <integer>
Maximum display width, 0 to disable
json formatter:
--noindent whether to disable indenting the JSON
CSV Formatter:
--quote {all,minimal,none,nonnumeric}
when to include quotes, defaults to nonnumeric
# ara result list
+--------------------------------------+-----------+--------------------+---------+--------+---------+-------------+---------------+---------------------+---------------------+
| ID | Host | Task | Changed | Failed | Skipped | Unreachable | Ignore Errors | Time Start | Time End |
+--------------------------------------+-----------+--------------------+---------+--------+---------+-------------+---------------+---------------------+---------------------+
| 79ee4b5b-667d-43a1-b10d-b48ebf422141 | localhost | Ping | False | False | False | False | False | 2016-05-14 03:27:39 | 2016-05-14 03:27:39 |
| b3a04d9e-c9df-4126-8481-5bdb9d9795f7 | localhost | Really debug thing | False | False | False | False | False | 2016-05-14 03:27:39 | 2016-05-14 03:27:39 |
+--------------------------------------+-----------+--------------------+---------+--------+---------+-------------+---------------+---------------------+---------------------+
# ara result show b3a04d9e-c9df-4126-8481-5bdb9d9795f7 --long
+---------------+-----------------------------------------------------------+
| Field | Value |
+---------------+-----------------------------------------------------------+
| ID | b3a04d9e-c9df-4126-8481-5bdb9d9795f7 |
| Host | localhost |
| Task | Really debug thing (1d24921e-bebc-4732-a362-32df24c8cb8b) |
| Changed | False |
| Failed | False |
| Skipped | False |
| Unreachable | False |
| Ignore Errors | False |
| Time Start | 2016-05-14 03:27:39 |
| Time End | 2016-05-14 03:27:39 |
| Result | { |
| | "_ansible_no_log": false, |
| | "_ansible_verbose_always": true, |
| | "changed": false, |
| | "failed": false, |
| | "msg": "Really debug thing", |
| | "skipped": false, |
| | "unreachable": false |
| | } |
+---------------+-----------------------------------------------------------+
Browsing the web interface¶
The web UI frontend is a visualization of the data recorded in the database. It provides insight on your playbooks, your hosts, your tasks and the results of your playbook run.
The interface provided by ARA provides is a simple Flask application. There are currently two documented options to host the web interface:
1. Embedded development server (easiest but least performance) 3. Apache with mod_wsgi (recommended)
These should be enough to get you started or help you choose your own path on other deployment options you might be used to when hosting Flask applications.
Generating a static HTML version of the web application¶
ARA is able to generate a static html version of it’s dynamic, database-driven web application.
This can be useful if you need to browse the results of playbook runs without having to rely on the database backend configured.
For example, in the context of continuous integration, you could run an Ansible job with ARA, generate a static version and then recover the resulting build as artifacts of the jobs, allowing you to browse the results in-place.
This is done with the ara generate html command.
Note
Hosting statically generated reports is not very efficient at a large scale. Please refer to: Advanced use cases.
By default, ARA will generate a static version for all the recorded playbook
runs in it’s database.
It is also possible to generate a report for one or many specific playbooks.
This is done by retrieving the playbook IDs you are interested in with
ara playbook list and then using the ara generate html command with the
--playbook parameter:
$ ara help generate html
usage: ara generate html [-h] [--playbook <playbook> [<playbook> ...]] <path>
Generates a static tree of the web application
positional arguments:
<path> Path where the static files will be built in
optional arguments:
-h, --help show this help message and exit
--playbook <playbook> [<playbook> ...]
Only include the specified playbooks in the
generation.
$ ara generate html /tmp/build/
Generating static files at /tmp/build/...
Done.
$ tree /tmp/build/
/tmp/build/
├── host
│ ├── anotherhost
│ ├── index.html
│ └── localhost
├── index.html
├── play
│ └── play
│ └── 6ec9ef1d-dd73-4378-8347-1242f6be8f1e
├── playbook
│ ├── bf81a7db-b549-49d9-b10e-19918225ec60
│ │ ├── index.html
│ │ └── results
│ │ ├── anotherhost
│ │ │ ├── index.html
│ │ │ └── ok
│ │ └── localhost
│ │ ├── index.html
│ │ └── ok
│ └── index.html
├── result
│ ├── 136100f7-fba7-44ba-83fc-1194509ad2dd
│ ├── 37532523-b2ec-4931-bb73-3c7e5c6fa7bf
│ ├── 3cef2a10-8f41-4f01-bc49-12bed179d7e9
│ └── e3b7e172-c6e4-4ee4-b4bc-9a51ff84decb
├── static
│ ├── css
│ │ ├── ara.css
│ │ ├── bootstrap.min.css
│ │ └── bootstrap-theme.min.css
│ └── js
│ ├── bootstrap.min.js
│ └── jquery-2.2.3.min.js
└── task
├── 570fe763-69bb-4141-80d4-578189c5938b
└── 946e1bc6-28b9-4f2f-ad4f-75b3c6c9032d
13 directories, 22 files
Generating a static junit version of the task results¶
ARA is able to generate a junit xml report that contains task results and their status.
This is done with the ara generate junit command.
By default, ARA will generate a report on all task results across all the
recorded playbook runs in it’s database.
It is also possible to generate a report for one or many specific playbooks.
This is done by retrieving the playbook IDs you are interested in with
ara playbook list and then using the ara generate junit command with the
--playbook parameter:
$ ara help generate junit
usage: ara generate junit [-h] [--playbook <playbook> [<playbook> ...]]
<output file>
Generate junit stream from ara data
positional arguments:
<output file> The file to write the junit xml to. Use "-" for
stdout.
optional arguments:
-h, --help show this help message and exit
--playbook <playbook> [<playbook> ...]
Only include the specified playbooks in the
generation.
$ ara generate junit -
<?xml version="1.0" ?>
<testsuites errors="0" failures="3" tests="66" time="33.0">
<testsuite errors="0" failures="3" name="Ansible Tasks" skipped="5" tests="66" time="33">
<testcase classname="localhost._home_dev_ara_ara_tests_integration_smoke_yml.ARA_Tasks_test_play" name="Deferred setup" time="3.000000"/>
<testcase classname="localhost._home_dev_ara_ara_tests_integration_smoke_yml.ARA_Tasks_test_play" name="include"/>
<testcase classname="localhost._home_dev_ara_ara_tests_integration_smoke_yml.ARA_Tasks_test_play" name="Ensure temporary directory exists"/>
<testcase classname="localhost._home_dev_ara_ara_tests_integration_smoke_yml.ARA_Tasks_test_play" name="Check if a file exists"/>
<testcase classname="localhost._home_dev_ara_ara_tests_integration_smoke_yml.ARA_Tasks_test_play" name="Touch a file if it doesn't exist"/>
<testcase classname="localhost._home_dev_ara_ara_tests_integration_smoke_yml.ARA_Tasks_test_play" name="Remove a file if it doesn't exist"/>
<testcase classname="localhost._home_dev_ara_ara_tests_integration_smoke_yml.ARA_Tasks_test_play" name="Remove a file if it exists">
[...]
Generating a static subunit version of the task results¶
ARA is able to generate a subunit report that contains task results and their status.
This is done with the ara generate subunit command.
By default, ARA will generate a report on all task results across all the
recorded playbook runs in it’s database.
It is also possible to generate a report for one or many specific playbooks.
This is done by retrieving the playbook IDs you are interested in with
ara playbook list and then using the ara generate subunit command with the
--playbook parameter:
$ ara help generate subunit
usage: ara generate subunit [-h] [--playbook <playbook> [<playbook> ...]]
<output file>
Generate subunit binary stream from ARA data
positional arguments:
<output file> The file to write the subunit binary stream to. Use
"-" for stdout.
optional arguments:
-h, --help show this help message and exit
--playbook <playbook> [<playbook> ...]
Only include the specified playbooks in the
generation.
$ ara generate subunit - | subunit2csv
test,status,start_time,stop_time
50d4e04fe034bea7479bc4a3fa3703254298baa8,success,2017-07-28 03:07:21+00:00,2017-07-28 03:07:21+00:00
a62f7a36683972efe1ef6e51e389417521502153,success,2017-07-28 03:07:22+00:00,2017-07-28 03:07:22+00:00
8902778f958439806aee2a22c26d8b79dc61c964,success,2017-07-28 03:07:22+00:00,2017-07-28 03:07:22+00:00
fd2d199b22b635ed82b41d5edf8c1774f64484dc,success,2017-07-28 03:07:22+00:00,2017-07-28 03:07:22+00:00
[...]