ARA Records Ansible — Ansible Playbook Reporting & Visualization¶

Scope: ARA (ARA Records Ansible) — an open-source Ansible callback plugin and Django-based reporting server that records every ansible and ansible-playbook run, exposes results via CLI, REST API, and a self-hosted web UI, and integrates with CI/CD, Prometheus, and LLMs via an MCP server.

Version covered: 1.8.0 (July 2026) License: GPLv3 Repository: codeberg.org/ansible-community/ara (mirrors: GitHub) Website: https://ara.recordsansible.org

Executive Summary¶

ARA (Another Recursive Acronym) Records Ansible and makes it easier to understand and troubleshoot playbook runs. It is an Ansible callback plugin that captures every playbook execution — tasks, hosts, results, facts, files, and metadata — and stores them in a database (SQLite, MySQL, or PostgreSQL). The recorded data is accessible through:

• CLI (ara playbook list, ara host show, etc.) for scripting and terminal workflows
• REST API for programmatic access and integrations
• Web UI (self-hosted Django app) for visual browsing, filtering, and debugging
• Prometheus exporter for metric scraping and alerting
• MCP Server for LLM-driven analysis and troubleshooting

ARA is non-invasive: it works with existing Ansible setups, CI/CD pipelines (Jenkins, Rundeck, Zuul), git forges (GitHub, GitLab, Gitea, Forgejo), and tools like AWX, Ansible Runner, Ansible Navigator, Molecule, and Semaphore.

Architecture & How It Works¶

The ara_default callback plugin is the core component. It hooks into Ansible's notification system and collects data as the playbook runs:

• Tasks — name, action (module), status, duration
• Hosts — inventory name, facts (OS, kernel, Python, etc.)
• Results — stdout, stderr, return code, diff, error messages
• Files — playbook content, roles, tasks, templates, variables
• Metadata — user, controller, Ansible version, Python version, CLI arguments, labels

This data is sent to the ARA API (either directly via Python in-process with the offline client, or over HTTP to a remote server).

Core Features¶

Recording Workflow¶

Installation Guide¶

Prerequisites¶

• Python >= 3.10
• Ansible (or ansible-core) installed for the same Python interpreter as ARA
• Linux or macOS

Option 1: Local Recording (No Server) — Quick Start¶

This is the simplest mode. ARA records to a local SQLite database and you can launch a lightweight web UI on demand.

# 1. Install Ansible and ARA (with server dependencies for the web UI)
python3 -m pip install --user ansible "ara[server]"

# 2. Enable the ARA callback plugin
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"

# 3. Run a playbook as usual
ansible-playbook playbook.yml

# 4. List recorded playbooks via CLI
ara playbook list

# 5. Launch the web UI (serves at http://127.0.0.1:8000)
ara-manage runserver

Option 2: Persistent API Server (Docker)¶

For team dashboards, CI/CD aggregation, or long-term storage, run the ARA API server in a container:

# Create a data directory for settings and SQLite database
mkdir -p ~/.ara/server

# Start the API server (Docker)
docker run --name api-server --detach --tty \\
  --volume ~/.ara/server:/opt/ara -p 8000:8000 \\
  docker.io/recordsansible/ara-api:latest

# Or with Podman
podman run --name api-server --detach --tty \\
  --volume ~/.ara/server:/opt/ara -p 8000:8000 \\
  quay.io/recordsansible/ara-api:latest

Then configure clients to send data to it:

# Install only ARA (no server dependencies needed on the client)
python3 -m pip install --user ansible ara

# Configure the callback
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"

# Point to the API server
export ARA_API_CLIENT="http"
export ARA_API_SERVER="http://127.0.0.1:8000"

# Run a playbook
ansible-playbook playbook.yml

# Query remotely
ara playbook list

Option 3: Persistent API Server (Manual Install)¶

# Install with server dependencies
python3 -m pip install --user "ara[server]"

# Create a settings directory
mkdir -p ~/.ara/server

# Run database migrations
ara-manage migrate

# Create a superuser for the web UI
ara-manage createsuperuser

# Start the server (production: use gunicorn/uwsgi behind nginx)
ara-manage runserver 0.0.0.0:8000

Option 4: Database Backends (MySQL / PostgreSQL)¶

Set environment variables before starting the API server:

export ARA_DATABASE_ENGINE=mysql        # or postgresql
export ARA_DATABASE_NAME=ara
export ARA_DATABASE_USER=ara
export ARA_DATABASE_PASSWORD=secret
export ARA_DATABASE_HOST=db.example.com
export ARA_DATABASE_PORT=3306

# Then migrate and run as usual
ara-manage migrate
ara-manage runserver

Distribution Packages¶

Best practice: For production, use PyPI or the official container images. Distribution packages may lag behind. [1][6]

Configuration¶

Environment Variables¶

ARA is configured primarily through environment variables:

ansible.cfg¶

Equivalent settings can be placed in ansible.cfg:

[ara]
api_client = http
api_server = https://ara.example.com
api_username = user
api_password = password
callback_threads = 4
default_labels = prod,deploy
ignored_facts = all
localhost_as_hostname = true

Server Configuration¶

For the API server itself (set before starting ara-manage):

CLI Usage & Examples¶

Playbooks¶

# List recent playbooks
ara playbook list

# Filter by status
ara playbook list --status failed

# Filter by name or label
ara playbook list --name "deploy prod"
ara playbook list --label prod

# Show detailed info
ara playbook show 42

# Get playbook metrics
ara playbook metrics

# Delete old playbooks (older than 30 days)
ara playbook prune --days 30 --confirm

# Output as JSON
ara playbook list -f json

Tasks & Results¶

# List tasks for a playbook
ara task list --playbook 42

# Show task detail with source code
ara task show 1234

# List failed results
ara result list --status failed

# Show full result (stdout, stderr, return code)
ara result show 5678

Hosts¶

# List hosts
ara host list

# Show host facts
ara host show hostname.example.com

# Host metrics
ara host metrics

Records (Custom Metadata)¶

# List all records attached to playbooks
ara record list

# Show a specific record
ara record show 99

Data Lifecycle¶

# Expire playbooks stuck in "running" state for >24 hours
ara expire --hours 24 --confirm

Ansible Plugins & Use Cases¶

ara_record — Attach Metadata to Reports¶

Attach arbitrary data to playbook reports from within your playbooks:

- name: Record git version
  ara_record:
    key: "git_version"
    value: "{{ lookup('pipe', 'git rev-parse HEAD') }}"
    type: "text"     # text, url, json, list, dict

Types control how the data is rendered in the web UI:

- name: Record different data types
  ara_record:
    key: "{{ item.key }}"
    value: "{{ item.value }}"
    type: "{{ item.type }}"
  loop:
    - { key: "log", value: "Deployment complete", type: "text" }
    - { key: "ci_link", value: "https://ci.example.com/build/42", type: "url" }
    - { key: "artifacts", value: '{"version": "2.1.0"}', type: "json" }

Attach data after a playbook completes by specifying its ID:

ansible localhost -m ara_record \\
  -a "playbook=14 key=logs value={{ lookup('file', '/var/log/deploy.log') }}"

ara_playbook — Query Playbook Info from Ansible¶

- name: Get current playbook info
  ara_playbook:
  register: query

- name: Print link to this playbook's report
  debug:
    msg: "https://ara.example.com/playbooks/{{ query.playbook.id }}.html"

ara_api — Free-Form API Queries¶

- name: Count failed hosts across all playbooks
  ara_api:
    path: /api/v1/hosts?status=failed&limit=1
  register: result

Prometheus Exporter (New in 1.8.0)¶

ARA 1.8.0 (July 2026) introduces a built-in Prometheus exporter [5]:

# Start the exporter on :8001/metrics
ara prometheus --bind 0.0.0.0:8001

Exposed metrics include playbook counts by status, task durations, host result counts, and scrape health indicators. Includes example Prometheus rules and Grafana dashboard guidance in the documentation.

MCP Server — LLM-Driven Troubleshooting¶

ARA ships an optional Model Context Protocol (MCP) server that gives LLMs read-only access to recorded playbook data [3][4]. Models can analyze failures, compare runs, detect performance regressions, and identify secret leaks — all without dumping 60K+ tokens of terminal output into the context.

# Clone the repo and set up a virtualenv
git clone https://codeberg.org/ansible-community/ara ~/.ara/git/ara
cd ~/.ara/git/ara
python3 -m venv .venv
.venv/bin/pip install httpx mcp

Configure in your MCP client (Claude Code, VS Code, Cursor, Ollama, etc.):

{
  "mcpServers": {
    "ara": {
      "command": "/home/user/.ara/git/ara/.venv/bin/python",
      "args": ["/home/user/.ara/git/ara/contrib/mcp/ara_mcp.py"],
      "env": {
        "ARA_API_SERVER": "http://127.0.0.1:8000"
      }
    }
  }
}

The server exposes 13 tools across two categories [4]:

Foundation tools (direct API-to-text): get/list playbooks, tasks, hosts, results, files.

Wrapper tools (aggregated analysis): - troubleshoot_playbook — aggregates failures, code context, host facts, and a summary for debugging - troubleshoot_host — host-centric failure view - analyze_performance — cross-run timing analysis, slowest tasks, variance detection

Works with any MCP-compatible client and any model that supports tool use — including open-weight models like Qwen3, Devstral, GLM, and GPT-OSS.

Distributed SQLite Backend¶

For CI/CD environments where many jobs run concurrently, ARA supports a distributed SQLite mode. Instead of fighting SQLite's write concurrency limits, each CI job records to its own database. The ARA API server dynamically loads the correct database based on the URL path.

/var/www/logs/
├── job-1/ara-report/ansible.sqlite
├── job-2/some/path/ara-report/ansible.sqlite
└── job-3/dev/ara-report/ansible.sqlite

Configure with:

export ARA_DISTRIBUTED_SQLITE=true
export ARA_DISTRIBUTED_SQLITE_ROOT=/var/www/logs

The server then serves: - http://example.org/job-1/ara-report - http://example.org/job-2/some/path/ara-report

This approach is ideal for CI systems (Zuul, Jenkins) where each job produces its own artifact.

Web UI¶

The ARA web reporting interface is a self-hosted Django application that provides:

• Dashboard — overview of recent playbooks with status indicators
• Playbook view — detailed breakdown of plays, tasks, results per host
• Host view — facts and result history per host
• File browser — view recorded playbook/task/role source files with line-level context for results
• Search & filter — by name, label, status, user, controller, date range
• Static generation — ara-manage generate /path/to/output for offline archives

A live demo is available at https://demo.recordsansible.org.

Live Demo¶

Explore a live instance of ARA populated with real playbook data:

• URL: https://demo.recordsansible.org
• API: https://demo.recordsansible.org/api/v1/
• Pre-loaded with playbooks from the ARA project's own CI

Tip: Use the API browser at https://demo.recordsansible.org/api/v1/ to explore the data model interactively — playbooks, tasks, hosts, results, and files are all linked by RESTful relationships.

Community & Project Status¶

The project is part of the ansible-community organization on GitHub, with primary development on Codeberg.

Community resources: - Blog: https://ara.recordsansible.org/blog/ - Documentation: https://ara.readthedocs.io/ - Ko-fi (support): https://ko-fi.com/rfc2549

References¶

Last updated: 2026-07-30