Understand metrics service architecture

Learn the architectural components and deployment topology of metrics service to make informed infrastructure decisions and ensure successful integration with Ansible Automation Platform.

Metrics service overview
Copy link

Metrics service is a Django-based application component of Ansible Automation Platform 2.7. It collects anonymized usage and performance data from your automation controller. The service runs as containerized workloads managed by either systemd (containerized installer) or Kubernetes (operator). It maintains its own PostgreSQL database and read-only access to the controller database.

Default behavior in Ansible Automation Platform 2.7
Copy link

Metrics service is enabled by default in Ansible Automation Platform 2.7 for both operator-based (OpenShift) and containerized installations that include automation controller. It is deployed automatically as a required component when you install automation controller.

  • Containerized installations: [automationmetrics] inventory group is required when installing Ansible Automation Platform if automationcontroller is present in the inventory file, unless automationmetrics_skip_install=true is set in [all:vars]
  • Operator installations: Enabled when metrics.disabled: false is set in the AnsibleAutomationPlatform custom resource. Operator deployments do not support automationmetrics_skip_install; they use metrics.disabled: true in the CR instead.

Key characteristics
Copy link

  • Django-based application: Built on Django framework with database migrations managed through /app/scripts/init.sh
  • Containerized deployment: Runs as three containers (automation-metrics-web, automation-metrics-tasks, automation-metrics-scheduler) managed by systemd (containerized installer) or Kubernetes (operator)
  • Optional deployment: Set automationmetrics_skip_install=true to opt out of metrics service installation when automation controller is present (containerized installations only)
  • Automatic anonymization: Customer-defined object names are replaced with "Custom" before transmission. Only built-in object names and publicly available collection names are sent in their original form
  • Auto-configured ingress: Establishes secure connection to Red Hat Data Ingress without manual setup
  • Read-only access: Accesses automation controller database in read-only mode to prevent operational impact
  • Isolated database: Maintains its own metrics_service database for metrics processing and storage
  • Health monitoring: Provides a health check endpoint at /health/. Returns {"status": "healthy", "checks": {...}} when healthy; returns HTTP 503 and {"status": "unhealthy", ...} on database connectivity failure.
  • HTTP proxy support: Supports HTTP/HTTPS proxy configuration for environments without direct internet access
  • Startup validation: Validates required production environment variables at startup. Containers exit immediately with validation errors if required variables are missing or invalid
  • Deployment flexibility: Supports both RHEL-based containerized deployments and OpenShift operator-based deployments with different configuration approaches

Capabilities unavailable without metrics service

  • Automation dashboard has no backend data source and is non-functional
  • No anonymized usage data is collected or transmitted
  • ROI calculations, automation savings, and executive reporting are unavailable
  • Dashboard collection tasks do not run

Relationship to automation dashboard
Copy link

Metrics service serves as the unified backend for automation dashboard. Metrics service collects additional dashboard-specific metrics, including:

  • Cost and pricing data for ROI calculations
  • Automation savings metrics
  • Executive reporting data

Dashboard collection is enabled by default when metrics service is installed. Dashboard data is collected through an initial backfill on first enable, then kept current through the hourly metrics collection pipeline. Dashboard data cleanup runs daily at 5:30 AM and 5:45 AM UTC.

Indirect node collection
Copy link

In addition to direct automation controller usage data, metrics service can collect indirect node audit data. Indirect node audit data is a daily, anonymized count of the devices that your automation acts on but that are not members of an automation controller inventory (for example, network switches, routers, and cloud resources configured through a vendor API). Indirect node collection is enabled by default in Ansible Automation Platform 2.7.

The controller.main_indirectmanagednodeaudit collector is enabled in daily mode as of Ansible Automation Platform 2.7. Indirect node audit records are collected through the analytics payload store and are accessible through the analytics API at /api/metrics/v1/analytics/controller.main_indirectmanagednodeaudit/.

Architecture components
Copy link

Core components

Component Container Name Purpose
Metrics service (web) automation-metrics-web Nginx reverse proxy + Gunicorn serving the Django application. Health endpoint: /health/
Metrics service (tasks) automation-metrics-tasks Async task worker for background job execution
Metrics service (scheduler) automation-metrics-scheduler APScheduler process that triggers periodic data collection tasks
metrics_service database PostgreSQL database Stores processed metrics data, analytics payloads, and configuration
awx/automation controller database (read-only) PostgreSQL database Source of automation controller usage data. Accessed via ms_awx_readonly user (SELECT-only)

Database architecture

Database User Privileges Purpose
metrics_service metrics_service ALL Metrics service own data storage, schema migrations, configuration, and analytics payload store
awx/automation controller ms_awx_readonly SELECT ON ALL TABLES IN SCHEMA public Read-only access to controller data for metrics collection
Note

The two-database model ensures metrics service cannot modify controller data. The ms_awx_readonly user has only SELECT privileges on the automation controller database.

 Important

If the automation controller database is unreachable, metrics service defers all collection tasks until connectivity is restored. This applies to all deployment topologies. When the controller database is unavailable, the analytics API cluster_id field is null, which may affect attribution in external analytics tools.

Deployment topology options
Copy link

The following table shows analytics API availability by deployment topology:

Topology INSTALL_TYPE Analytics API available Notes
AIO Growth (All-in-One) containerized Yes Single host, automation controller and metrics service co-located
Enterprise Multi-Node containerized Yes Dedicated metrics service node
Operator (OpenShift) operator Yes Managed by Kubernetes operator; metrics service auto-provisioned
Managed cloud (Red Hat-hosted) operator Yes Metrics service pre-installed; no manual deployment required

To skip metrics service installation in containerized deployments, set automationmetrics_skip_install=true in [all:vars] and omit the [automationmetrics] inventory group.

Deployment method comparison
Copy link

Metrics service supports two deployment methods with different configuration complexity and automation levels:

Aspect Containerized Installer Operator (OpenShift)
Deployment method Ansible role (automationmetrics) in containerized installation program Kubernetes operator (automation-metrics-operator) managed by AAP gateway operator
Configuration complexity Manual: requires inventory file edits, database passwords, network variables Automatic: single CR field (metrics.disabled: false)
Database provisioning Administrator provisions databases and configures credentials in inventory Operator automatically provisions databases and manages credentials via Kubernetes secrets
Auto-installation Explicit: [automationmetrics] inventory group required Automatic: pre-installed in managed cloud; metrics.disabled: false in on-premise operator CR
Opt-out mechanism automationmetrics_skip_install=true in [all:vars] metrics.disabled: true in AnsibleAutomationPlatform CR

Containerized installer deployment details
Copy link

Metrics service is deployed through the automationmetrics Ansible role. Hosts must be added to [automationmetrics] inventory group unless automationmetrics_skip_install=true is set.

Operator-based deployment details
Copy link

Metrics service is deployed through the automation-metrics-operator running on OpenShift. The AAP gateway operator manages the metrics operator lifecycle. Database unreachability behavior applies to operator deployments in the same way as all other topologies; see the note in the Architecture components section.

Analytics API
Copy link

Metrics service exposes an analytics API that provides authorized external tools with direct access to collected metrics data. The API is mounted at /api/metrics/v1/analytics/ through the platform gateway. Use this API to integrate collected automation data with your own business intelligence (BI) or reporting tools.

The API requires the System Administrator or Platform Auditor role. All requests must be authenticated through the platform gateway.

Two data paths: analytics payload store and anonymized telemetry

Metrics service uses two distinct data paths for collected metrics data.

The analytics payload store is a purpose-built data path for the analytics API. When a collector's gather() call completes successfully, the raw output is persisted to the AnalyticsPayload table in the metrics service database before any rollup or anonymization step runs. This raw payload is then served verbatim through the analytics API. Joins, aggregations, or other transformations are performed on the customer side using your own BI tooling (a bring-your-own-BI pattern).

The anonymized telemetry path is a separate pipeline that processes collected data through a rollup() and prepare() step, replaces customer-defined object names with "Custom", and transmits the result to Red Hat's data ingress endpoint via Segment.com. This path is used to power product usage analytics for Red Hat.

The two paths are independent: analytics payloads written to the AnalyticsPayload table are raw and unmodified, while the anonymized telemetry path operates on separately processed data. Data served through /api/metrics/v1/analytics/ is always the pre-prepare() output from gather().

Available operations

Operation Endpoint Method Description
Discovery /api/metrics/v1/analytics/ GET Returns the list of available collectors and their metadata.
Data retrieval /api/metrics/v1/analytics/collector/ GET Returns paginated rows of collected data for the specified collector. Supports since and until query parameters.
On-demand collection /api/metrics/v1/analytics/collector/collect/ POST Triggers an immediate collection run for the specified collector. Returns HTTP 202 Accepted.

Collectors

The analytics API exposes 28 enabled collectors across three collection modes:

  • Hourly collectors (10): Collect automation activity data every hour, including job host summaries, unified jobs, credentials, and job event data.
  • Snapshot collectors (15): Collect point-in-time configuration data daily, including execution environments, system configuration, controller version, table metadata, and feature flags.
  • Daily collectors (3): Collect aggregated daily metrics. The three daily collectors exposed through the analytics API are controller.main_host_daily, controller.main_hostmetric, and controller.main_indirectmanagednodeaudit.

AnalyticsPayload table schema

Each record written to the AnalyticsPayload table represents a single successful collection run for one collector. The following fields are stored for each payload:

Field Type Description
collector string Public collector name in group.function format (for example, controller.main_indirectmanagednodeaudit). This is the API path segment and the value stored in the database.
source string Originating platform component. Defaults to local for the local automation controller instance.
cluster_id string (nullable) Controller installation UUID read from the AWX database. Null if the controller database was unreachable at collection time. A null cluster_id does not prevent payload persistence or API access.
since datetime (nullable) Inclusive start of the collection window passed to the collector. Null for snapshot collectors, which do not accept a time window.
until datetime (nullable) Exclusive end of the collection window passed to the collector. Null for snapshot collectors.
started_at datetime Timestamp when the gather() call started executing.
finished_at datetime Timestamp when the gather() call completed.
payload JSON Raw output from gather() before any prepare() or anonymization step. A list of record dicts for DataFrame collectors; a dict for snapshot collectors such as config.

Payload retention

Analytics payloads are retained based on the Controller cleanup_jobs schedule. When the Controller is reachable, the retention period is resolved dynamically from the lowest valid positive days value among enabled cleanup_jobs schedules. When no valid enabled schedule with a positive days value exists, or when the Controller is unreachable, a 90-day fallback applies. You can override retention for manual task runs using the analytics_retention_days parameter.

Cluster identification

Each analytics payload includes a cluster_id field that identifies the automation controller instance. The cluster_id value equals the controller installation UUID. If the automation controller database is unreachable at collection time, cluster_id is null. This condition is non-fatal: the payload is still persisted and available through the API, but attribution by cluster in external analytics tools may be affected until connectivity is restored.