ARA Records Ansible: a callback plugin that turns playbook runs into a searchable database

A callback plugin records every task result without touching the playbooks

ARA works through Ansible's standard callback plugin mechanism rather than wrapping the ansible binary or replacing the inventory system. One environment variable is all that is required to activate it:

export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"

Set that variable, then run any playbook as normal with ansible-playbook playbook.yml. From that point, every task result, every host outcome and every play event flows from Ansible's own reporting hooks to ara's storage layer. No playbook modification is needed and no instrumentation library needs importing.

Data lands in SQLite by default for a local setup, or in MySQL or PostgreSQL when a persistent server is configured. A Django REST API server sits between the callback plugin and the storage layer, and that architecture means the same recording mechanism works whether data goes to a file on the same machine or to a shared server aggregating results from dozens of different environments.

Platform and interpreter requirements are specific and non-negotiable

Python 3.10 is the floor for both the host and the interpreter used by Ansible. pyproject.toml lists classifiers for Python 3.10 through 3.14, and Mac OS works alongside Linux distributions as long as a supported Python version is available. An older interpreter on the same machine needs a separate virtualenv to isolate a compliant Python version.

One constraint that surprises people: both Ansible and ara must share a Python interpreter. If Ansible runs in one virtualenv and ara sits in a different one, the callback plugin cannot be found at all. For environments where Ansible came from a distribution package and Python 3.10 lives only in a user-managed venv, the correct install target is inside the same environment as Ansible.

For CI/CD platforms, the README lists Jenkins, Rundeck and Zuul as supported environments. It also covers AWX and Automation Controller (Tower), Molecule and Semaphore. Git forge automation on GitHub, GitLab, Gitea and Forgejo is included in the list. On all of these, the requirement is the same: ara and Ansible share a Python interpreter.

pip install ara[server] and a single export start local recording

For a setup that records locally with no external server, one pip command installs both Ansible and ara with the server dependencies included:

python3 -m pip install --user ansible "ara[server]"

After setting the callback plugin variable and running a playbook, ara populates its local SQLite database. Two CLI commands give immediate access to what was recorded:

ara playbook list
ara host list

To see the web interface, the ara-manage runserver command starts a local Django development server at http://127.0.0.1:8000. This is the local-first mode: everything stays on the same machine, no network configuration is required, and SQLite is the only dependency beyond Python.

For a server deployment that aggregates results from multiple machines, the documentation recommends the ara_api Ansible role from the ara collection on Ansible Galaxy. Container images are published on DockerHub as docker.io/recordsansible/ara-api:latest and on Quay as quay.io/recordsansible/ara-api:latest. Starting the server with Docker requires mapping a volume for storage:

mkdir -p ~/.ara/server
docker run --name ara-api --detach --tty \
  --volume ~/.ara/server:/opt/ara -p 8000:8000 \
  docker.io/recordsansible/ara-api:latest

Once the server runs, each client machine installs ara without server dependencies, sets the callback plugin, and points two additional environment variables at the server:

export ARA_API_CLIENT="http"
export ARA_API_SERVER="http://127.0.0.1:8000"

CLI commands cover playbooks, plays and hosts, with prune and expire for cleanup

Beyond the list command, ara's CLI exposes a set of subcommands for each recorded entity. From pyproject.toml, the registered entry points include playbook list, playbook show, playbook delete, playbook prune and playbook metrics, alongside play list, play show and play delete, as well as host list. Two additional commands handle maintenance: expire removes data past a configured age, and prometheus produces output for Prometheus scraping.

Playbook prune and expire address a practical concern that grows over time. A SQLite database that accumulates months of CI runs can become large, and without a cleanup mechanism the reporting UI becomes slower to query. Neither command's behaviour is documented in the README beyond the entry point name, so the ara.readthedocs.io documentation is where the options and thresholds live.

Playbook metrics and prometheus are the two outputs that connect ara to external monitoring. What each metric covers and which version of Prometheus is required are questions for the documentation rather than the README.

Authentication is absent by default, and the README says to enable it before production

ARA's web interface and REST API start without authentication. Anyone who can reach port 8000 on the server can read all recorded playbook results.

For a laptop running local SQLite recording, that is not a concern. For a shared server aggregating runs from a CI system, it is. The README calls this out directly in the Getting started section, pointing to ara.readthedocs.io/en/latest/api-security.html for instructions on enabling authentication before production use. No default credentials or token mechanism is described in the README itself.

This is a deployment decision to make early, not late. A server that goes live on an internal network without authentication is readable by anyone who discovers port 8000, and that includes the full task output, host names and variable values that Ansible logs during a run. Review the api-security documentation before exposing the server to any shared network.

ARA does not alert, does not enforce policy and does not replace AWX

Recording what happened is what ara does. Deciding what to do next is outside its scope.

No alert mechanism appears in the README or pyproject.toml. A playbook that fails is recorded, and that failure is visible in the UI or via the REST API, but ara does not send a notification. Any notification on failure requires an external system reading from ara's API or from Ansible's own notification callbacks.

Compared with AWX or Automation Controller, ara occupies a narrower position. AWX is a workflow scheduler and inventory manager that happens to record run results. ARA is a run recorder that does nothing to schedule or orchestrate. An organisation that already uses AWX has built-in run history; adding ara alongside it is a duplication unless the goal is to store results in a separately managed database for longer retention or different access controls.

For teams running Ansible from the command line or from CI pipelines that have no built-in run history, ara adds that record without requiring an infrastructure change beyond pip install and one environment variable.

GPL-3.0 and a non-commercial project supported by Ko-fi

ARA is distributed under the GNU General Public License version 3. pyproject.toml includes the license classifier, and the COPYRIGHT section in the README reproduces the GPLv3 header. For organisations with GPL compatibility requirements in their software stack, the full text of the license is in the LICENSE file at the repository root.

GPL-3.0 matters if you plan to embed ara in a commercial product or redistribute a modified version. Running ara internally to record your own Ansible runs is a different question than bundling it in a product, and the license text is the appropriate place to assess that boundary.

On governance, ara is explicitly non-commercial. Hosting, CI infrastructure, development and maintenance all cost money, and the README points to sticker sales and Ko-fi tips as the funding mechanism. Community channels include IRC on Libera.chat at #ara, Matrix bridged from IRC, Slack at arecordsansible.slack.com and Mastodon at fosstodon.org/@ara. Issue tracking and code are hosted on Codeberg rather than GitHub, at codeberg.org/ansible-community/ara.

Last push on 2026-07-13, changelog in git tags rather than GitHub releases

Last push to the repository was on 2026-07-13. It is not archived. Releases and changelog entries live in git tags on Codeberg rather than as GitHub releases, which means the GitHub releases listing shows nothing.

Finding the current version requires reading the git tags or the changelog documentation at ara.readthedocs.io/en/latest/changelog-release-notes.html. Version numbers are generated dynamically via setuptools-scm using the no-guess-dev scheme, so the version visible in an installed package reflects the tagged version, not a manually maintained constant.

For teams considering ara for long-term use, the Codeberg hosting is a factor. Contributions, issues and change history are on Codeberg. The GitHub repository at ansible-community/ara appears to be a mirror, and anyone who wants to follow development or file issues should go to codeberg.org/ansible-community/ara.

Editorial conclusion

ARA fits any team that already runs Ansible and wants a searchable history of playbook results without setting up a separate observability stack. It requires no changes to existing playbooks, only the ANSIBLE_CALLBACK_PLUGINS export before each run. Skip it if your requirement is real-time alerts or if your Ansible version ships with an incompatible Python, since the ara package must be installed under the same Python interpreter as Ansible. Before deploying the server for shared use, read the authentication documentation at ara.readthedocs.io/en/latest/api-security.html, because the server starts without authentication by default.

Frequently asked questions

Official sources

1. ansible-community/ara on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README