metrics-utility

metrics-utility deals with collecting, analyzing and reporting metrics from Ansible Automation Platform (AAP) Controller instances.

It provides two interfaces - a CLI and a python library.

Also see below for dev setup, and other docs.

CLI

A metrics-utility CLI tool for collecting and reporting metrics from Controller, allowing users to:

• Collect Controller usage data from the database, settings, and prometheus
• Analyze the data and generate .xlsx or .ods reports
• Support multiple storage adapters for data persistence (local directory, S3)
• Push metrics data to console.redhat.com

It can run either standalone (against a specified postgres instance), or inside the Controller's python virtual environment. The controller mode allows the config collector to collect more settings and takes DB connection details from there.

The billing workflow provides two primary commands:

• gather_automation_controller_billing_data
  • collects data from controller, saves daily tarballs with .csv / .json inside
  • saves tarballs in specified storage
  • optionally sends to console
• build_report
  • builds an .xlsx report by default, or an .ods report with --format=ods
    • 3 report types - CCSP, CCSPv2, RENEWAL_GUIDANCE
    • the ccsp* reports use the collected tarballs as the source
    • the renewal* report reads from controller db

The candlepin_manage command is an auxiliary management command for Candlepin consumer registration and certificate renewal; see python manage.py candlepin_manage --help.

Example invocation:

pip install metrics-utility

# common
export METRICS_UTILITY_SHIP_PATH="./out"
export METRICS_UTILITY_SHIP_TARGET="directory"

# gather data
metrics-utility gather_automation_controller_billing_data --ship --until=10m
ls out/data/`date +%Y/%m/%d`/ # data/<year>/<month>/<day>/<uuid>-<since>-<until>-<index>-<collection>.tar.gz

# build report
export METRICS_UTILITY_REPORT_TYPE="CCSPv2"

metrics-utility build_report --month=`date +%Y-%m` # year-month
metrics-utility build_report --month=`date +%Y-%m` --format=ods
ls out/reports/`date +%Y/%m`/ # reports/<year>/<month>/<type>-<year>-<month>.xlsx and .ods

See docs/cli.md and docs/old-readme.md for details on the usage,
See docs/environment.md for a full list of environment variables,
See docs/awx.md for more on running against an awx dev env. See docs/architecture.md for the system architecture and maintainer extension points.

Python library

The metrics_utility.library library provides a lower-level python API exposing the collection functionality using these abstractions:

• collectors - functions that collect specific data, from database to a .csv, or from elsewhere into a python dict
• storage - the segment.com storage backend (StorageSegment), used to push anonymized data
• db locking helper (lock)

It is complemented by the sibling metrics_utility.anonymized_rollups package, which rolls up and anonymizes collected data before shipping.

Both are shared with the external metrics-service, which is their main consumer. The library uses no env variables, and doesn't rely on Controller environment, taking everything via params. The CLI uses the library where possible, but is not limited to it, and keeps its own packaging/storage/report implementations under automation_controller_billing/.

Example use:

from metrics_utility.library.collectors.controller import config, main_jobevent
from metrics_utility.library import lock

db = ...  # django.db.connection / psycopg 3

with lock('my-unique-key', wait=False, db=db) as acquired:
    if not acquired:
        raise 'too bad'  # or use wait=True instead

    # dict, will be converted to json
    config_dict = config(db=db).gather()

    # list of .csv filenames; since is included, until is excluded
    # both datetime with timezone, or None
    job_csvs = main_jobevent(db=db, since=since, until=until).gather()

See library README for details.

Developer setup

Prerequisites

• Python 3.12 or later
• uv
• Docker compose
• make, git

Dependencies are managed via pyproject.toml (& uv.lock). There is also setup.cfg with dependencies but those are only used for the controller mode.

The Docker compose environment is used to provide a quick postgres & SeaweedFS (S3-compatible store) instances on ports 5432 and 8333, but they can be replaced with local setup. See docker-compose.yaml for details, and tools/docker/*.sql for users & data to import in postgres (start with roles.sql and latest.sql). (Or don't, and use docker.)

uv is also not required as long as you can manage your own python venv and install dependencies from pyproject.toml.

Optionally, uvx pre-commit install to run ruff checks from a pre-commit hook, defined in .pre-commit-config.yaml. Or you can run make lint / make fix manually.

Installation

# Clone the repository
git clone https://github.com/ansible/metrics-utility.git
cd metrics-utility

# Install dependencies using uv
uv sync

Run

cd metrics-utility
make compose

cd metrics-utility
uv run ./manage.py --help
uv run ./manage.py gather_automation_controller_billing_data --help
uv run ./manage.py build_report --help

make compose-pytest runs the test suite inside docker compose (also used in CI), make compose-env starts an interactive container with deps installed for manual testing.

make clean resets the docker environment, make lint & make fix run the linters & formatters, make psql runs psql in the postgres container.

See docs/tests-compose.md for more on running tests inside docker compose.

metrics-service

make compose-service runs the full metrics-service stack locally (web, dispatcher, scheduler), make compose-pytest-svc runs the metrics-service test suite with the local metrics-utility checkout.

Both require a ../metrics-service checkout.

Tests

Some tests depend on a running postgres & SeaweedFS instance - run make compose to get one.

make test runs the full test suite, make coverage produces a coverage report.

Use uv run pytest -s -v for running tests with verbose output, also accepts test filenames.

Documentation

More documentation is available in docs/, and elsewhere:

• CHANGELOG.md - changes between tagged releases
• LICENSE.md - the Apache-2.0 license
• README.md - this README
• docs/CONTRIBUTING.md - Contributor's guide
• docs/awx.md - running against awx dev env
• docs/cli.md - CLI docs
• docs/data-lineage.md - source fields, anonymized output trees, and dashboard dependencies
• docs/collectors-and-partitions.md - collectors overview and adding new ones
• docs/environment.md - Environment variables
• docs/event-data-unicode-escaping.md - investigation of event JSON Unicode escaping
• docs/org-aware-collectors.md - org-bearing collector payloads and service-side filtering guide
• docs/old-readme.md - pre-0.5 README, with more examples
• docs/report-lineage.md - required/default report data paths and optional-sheet dependency trees
• docs/tests-compose.md - running tests inside docker compose
• docs/vcpu.md - docs for the total workers vcpu collector
• metrics_utility/library/ - library documentation
• tools/anonymized_db_perf_data/ - perf test data for anonymization
• tools/collections/ - scripts for pulling list of collections from galaxy & automation hub
• tools/dashboard_perf/ - metrics-service dashboard collection benchmarks
• tools/docker/ - docker compose environment & mock awx data
• tools/perf/ - perf test data generator and scripts for build report
• tools/service_perf/ - metrics-service API & task benchmarks
• tools/testathon/ - data generator for testing

Please follow our Contributor's Guide for details on submitting changes and documentation standards.