Classify the first wrong observation
Capture one authorized occurrence with timestamp and timezone, Asterisk branch and package, node identity, requested scheme, host, port, prefix and URI, response status, authentication state, scraper target state, last successful scrape, sample metric and labels, query range, retention and series count. Redact secrets without removing the path or status evidence.
Classify the symptom as connection failure, TLS or proxy failure, 404-style wrong route, authentication challenge, service-unavailable response, empty or partial payload, scrape parsing failure, missing series, stale sample, wrong node, query error, duplicate identity or excessive time-series growth. These states have different owners.
Prove listener, prefix and metrics URI in order
Confirm the built-in HTTP server is enabled and bound only where intended. Preserve its address, port and configured prefix, then append the res_prometheus URI exactly once. A request sent to the wrong prefix or proxy path can return a different status than a request reaching the module callback.
Test locally or from the authorized monitoring segment before changing a firewall. If local access works and the scraper cannot connect, continue through route, policy, proxy, certificate and name-resolution evidence. Do not publish the listener to the Internet or disable network controls as a diagnostic shortcut.
Separate module load, enablement and authentication
Verify that the installed package contains res_prometheus, that the module loaded, that its configuration parsed and that statistics are enabled. Current source returns an authentication challenge when configured credentials are missing or wrong and a service-unavailable response when the module cannot handle the request because metrics are not enabled. Preserve the actual status and Asterisk log around the request.
Configure username and password as one change and update the scraper secret through its owner. Do not paste the password into a command transcript, ticket or dashboard. A successful authenticated response establishes access to the route only.
Compare missing series with loaded providers and live objects
Start with one core metric that should identify the running process, then inventory the actual response. If a provider-specific family is absent, compare the installed branch, loaded subsystem, provider registration, current objects and documented metric name before changing the query. A system with no matching object can legitimately emit no per-object series.
Keep endpoint, registration, channel and bridge states distinct. A missing outbound-registration series does not prove an endpoint is unreachable; a channel count does not equal user-visible calls; bridge membership does not prove decoded media. Use the owning CLI, SIP and call evidence for the service conclusion.
Diagnose stale samples and identity collisions
Compare target time, last scrape, scrape duration, response timestamp where available, Prometheus ingestion time, query window and dashboard refresh. Then verify that node labels, instance address and Asterisk entity identity have not been reused by another host or proxy target. A graph can look current while showing a different node, and a last value can remain visible after collection stopped.
Use target-up or equivalent collector evidence to distinguish a silent target from a flat service metric. Confirm that reload or restart changed the expected process properties only when that event actually occurred; do not force a reload to make a graph move.
Bound excessive cardinality and retest
Identify which metric family and labels drive the series count. On a branch that documents the detail switches, consider disabling per-channel or per-bridge detail through the configuration owner. On earlier branches, change collection or query design through the supported platform rather than adding an unknown option. Preserve the aggregate evidence and incident correlation requirement.
Retest one authenticated scrape, one stable core identity, the required provider series, collection interval, query and alert, then repeat a normal PBX control separately. Confirm credentials remain protected and the listener is no broader than before. No host, module, route, credential, metric, series, dashboard, alert, endpoint, call or media path was inspected or tested for this diagnostic.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk 23 res_prometheus configuration ↗
- Asterisk prometheus.conf sample ↗
- Asterisk res_prometheus implementation ↗
- Asterisk built-in HTTP server setup ↗
- Asterisk project release history ↗
- Prometheus overview and pull model ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.