Asterisk Prometheus metrics: module, HTTP route and cardinality boundaries

Map the complete pull path before enabling metrics

Prometheus pulls text metrics from an HTTP target. In Asterisk, res_prometheus registers a configurable URI with the built-in HTTP server; the module and HTTP server are therefore separate dependencies. Record the Asterisk process and branch, package source, loaded module, prometheus.conf owner, HTTP listener and prefix, metrics URI, authentication owner, permitted scraper address, transport protection and monitoring destination.

A running PBX, an enabled HTTP listener and a loaded metrics module are different states. A successful TCP connection does not prove the requested URI exists, and a valid metrics response does not prove that a particular endpoint, registration, channel or bridge is healthy.

Prove the installed branch and configuration surface

Asterisk documents res_prometheus from 17.0.0, with statistics disabled by default. Confirm that the installed package actually contains and loads the module, then compare its accepted options with the generated documentation for that branch. Do not copy a current sample over distribution-managed or FreePBX-generated configuration without identifying ownership and rollback.

The current API documentation is generated from branch 23. The project release page reviewed for this guide listed 22.11.0 and 23.5.0 releases while later 20.22, 22.12, 23.6 and 24.0 builds were still shown as release candidates. Treat a documented future or later-maintenance option as unavailable until the running binary accepts it.

Compose the HTTP prefix, route and access boundary

Asterisk requires its built-in HTTP server to be enabled for res_prometheus to function. The HTTP configuration can also set a listener address, port and URI prefix, while prometheus.conf sets the metrics URI. Preserve the resulting path exactly and test from the authorized scraper network rather than opening the listener broadly to make a probe succeed.

The module documentation strongly recommends Basic authentication because metrics expose useful system information. Supply both username and password, store the secret in the monitoring system, restrict the network path and prefer an approved protected transport or internal proxy design. A Basic-auth challenge is not encryption, and a dashboard link is not an authorization policy.

Inventory core and provider metrics separately

Core metrics can expose build properties, version, uptime, last reload and scrape duration when enabled. Additional metric families can come from registered providers and loaded subsystems. Inventory the actual response after every branch, package or module change; do not promise a metric merely because it exists in master source or another installation.

Tie every alert and dashboard panel to the exact metric name, label set, type and installed source. An absent series can mean the provider module is missing, the feature has no current objects, labels changed, the scrape failed or the query excluded it. Keep those explanations separate from a verified service outage.

Control label cardinality before collecting detail

Current Asterisk documentation marks per-channel state and duration series and per-bridge channel-count series as high-cardinality detail. It also lists switches to disable those detail families only in specific later maintenance versions: 20.22.0, 22.12.0, 23.6.0 and 24.1.0. Do not assume those controls exist on an earlier stable build.

Estimate the number of simultaneous channels, bridges, nodes and retained label combinations before enabling detailed collection. Set scrape interval and retention with the monitoring owner, observe time-series growth and query cost, and prefer bounded aggregate alerts where they answer the operational question. Lowering cardinality is not permission to discard the correlation evidence needed for an incident.

Accept the monitoring path and the service path independently

Validate an authenticated scrape, response status, content, stable target identity, timestamps, collection interval, retention, recording rules, dashboard queries and one authorized synthetic alert. Then validate the PBX service separately with its normal endpoint, registration, call, media and user-outcome evidence. A green scrape says the collector reached a metrics route; it does not prove call completion or audio.

Document ownership for the Asterisk module, HTTP listener, proxy or firewall, scraper, credentials, rules, dashboards and notifications. Preserve rollback and a monitoring-loss alert that does not depend on the missing target continuing to emit data. No host, metric, target, dashboard, alert, call or media path was tested for this guide.

Do not infer metrics exposure from a base listener

The HTTP service guide requires the metrics module, route, authentication and network policy to be proven after the Asterisk listener.

Keep dashboard history separate from Prometheus collection

The FreePBX Dashboard guide preserves each collector, interval, label and cache. A current dashboard graph does not prove the Prometheus target is fresh, and a green scrape does not prove the FreePBX card or call path.