Metrics

GET /metrics on the admin address (default http://127.0.0.1:9090/metrics) returns every metric in Prometheus text format. It needs no token because the admin address only listens on localhost. For how to scrape and alert, see Monitoring.

Counters (names ending in _total) only ever go up and reset when Quikcast restarts. Use rate() or increase() on them. Gauges go up and down. There are no per-mount or per-listener labels, so the number of series stays small and fixed no matter how busy the server gets. The only labelled metrics use a fixed set of reason values (see disconnect reasons).

Server

Metric	Type	Meaning
uptime_seconds	gauge	Seconds since the process started.
ready	gauge	1 while the server accepts new work, 0 while draining or shutting down.
config_generation	gauge	Starts at 1 and increases with every successful reload.
config_reload_attempts_total	counter	Reloads attempted.
config_reload_successes_total	counter	Reloads that were applied.
config_reload_failures_total	counter	Reloads that were rejected. The old config stayed active.
errors_total	counter	Error responses sent to clients.
admission_rejections_total	counter	Connections refused because a connection or handshake limit was full.
drain_rejections_total	counter	New work refused because the server is draining.
logging_dropped_total	counter	Log lines dropped because the log reader could not keep up.

Sources (encoders)

Metric	Type	Meaning
active_sources	gauge	Sources connected right now.
active_mounts	gauge	Mounts that currently have a source. Same value as active_sources.
source_connections_total	counter	Sources admitted since start.
source_auth_denials_total	counter	Source connections refused for a wrong password.
source_conflicts_total	counter	Source connections refused because the mount already has a source (or a relay).
source_access_denied_ip_total	counter	Source connections refused by source_access IP rules.
source_auth_duration_seconds	histogram	Time spent checking source credentials.
source_disconnects_total	counter	Sources that ended, by reason.
bytes_ingested_total	counter	Audio bytes accepted from sources and relays.
retained_audio_allocation_bytes	gauge	Memory currently reserved for retained audio.
metadata_updates_total	counter	Song title updates accepted.

Listeners

Metric	Type	Meaning
active_listeners	gauge	Listeners connected right now.
listeners_connected_total	counter	Listeners admitted since start.
listeners_disconnected_total	counter	Listeners that ended, by reason.
slow_consumers_total	counter	Listeners dropped for falling too far behind.
bytes_served_total	counter	Audio bytes sent to continuous-stream listeners, including embedded titles.
audio_bytes_served_total	counter	Of those, the audio itself.
icy_metadata_bytes_served_total	counter	Of those, embedded song-title blocks.
fallback_listener_admissions_total	counter	Listeners served by a fallback mount instead of the one they asked for.

Access control

Metric	Type	Meaning
listener_access_denied_ip_total	counter	Listeners refused by an IP rule.
listener_access_denied_geo_total	counter	Listeners refused by a country rule.
listener_access_denied_user_agent_total	counter	Listeners refused by a User-Agent rule.
listener_signed_auth_denied_total	counter	Listeners refused for a bad or expired signed link.
hls_signed_auth_denied_total	counter	The same, for HLS requests.

Relays

Metric	Type	Meaning
relay_attempts_total	counter	Connection attempts to upstreams.
relay_connections_total	counter	Successful connections to an upstream.
relay_failures_total	counter	Failed attempts.
relay_upstream_failures_total	counter	Failures caused by the upstream (as opposed to local problems).
relay_failovers_total	counter	Switches to the next upstream.
relay_cycles_exhausted_total	counter	Times every upstream failed and the relay had to back off.
relay_reconnects_total	counter	Reconnects after an earlier connection.
relay_response_body_bytes_total	counter	Bytes read from upstreams.
relay_audio_bytes_total	counter	Audio bytes demultiplexed from upstreams.
relay_metadata_rejections_total	counter	Invalid song titles from upstreams that were ignored.

HLS

Metric	Type	Meaning
hls_requests_total	counter	Public HLS requests.
hls_get_responses_total	counter	GET responses served.
hls_head_responses_total	counter	HEAD responses served.
hls_partial_responses_total	counter	206 Partial Content responses (byte ranges).
hls_not_modified_responses_total	counter	304 Not Modified responses.
hls_range_rejections_total	counter	Byte-range requests refused as unsatisfiable.
hls_rejections_total	counter	HLS requests and uploads that were rejected.
hls_bytes_served_total	counter	Body bytes of HLS responses.
hls_ingest_bytes_total	counter	Bytes of accepted segment and initialization uploads.
hls_segments_accepted_total	counter	Media segments accepted.
hls_initializations_accepted_total	counter	fMP4 initialization objects accepted.
hls_publications_total	counter	Playlist publications.
hls_active_uploads	gauge	Uploads in progress.
hls_stored_objects	gauge	Segments and initialization objects held in memory.
hls_stored_bytes	gauge	Bytes held in memory.
hls_allocation_reserved_bytes	gauge	Memory reserved against allocation_budget.

Disconnect reasons

listeners_disconnected_total and source_disconnects_total carry one reason label with a fixed set of values. All values always appear, even at zero.

Reason	Meaning
client_disconnected	The listener closed the connection.
source_disconnected	The encoder disconnected. Listeners ended with it.
slow_consumer	The listener fell behind the retained audio.
write_stall	The listener's connection stopped accepting data.
shutdown	The server was shutting down.
source_timeout	The encoder sent nothing for source_timeout_ms.
malformed_input	The source sent audio Quikcast could not parse.
internal_fault	An internal error. Please report it.
administrative_disconnect	An operator disconnected it through the API or console.

What is not measured

Listener numbers over time are not metrics. Use the /api/history endpoint for the last 24 hours, or graph active_listeners in your own Prometheus for longer.