Observability

Logging and metrics utilities shared by challenge services.

LokiHandler

Bases: Handler

Best-effort, non-blocking Loki push handler.

Enabled only when LOKI_PUSH_URL is set.

Metrics

Prometheus Pushgateway/Pushproxy helpers (best-effort).

from_env(ctf_slug, service) staticmethod

Create a Metrics instance based on standard deployment env vars.

new_counter(name, documentation, labelnames=())

Create a custom counter attached to the shared registry.

new_gauge(name, documentation, labelnames=())

Create a custom gauge attached to the shared registry.

new_histogram(name, documentation, *, buckets=None, labelnames=())

Create a custom histogram attached to the shared registry.

push()

Force a Pushgateway flush for newly updated custom metrics.

record_attempt(outcome, team=None, correct_digits=None)

Update counters and histograms for player attempts.

record_registration(outcome, team=None)

Track a registration attempt and store associated timestamps.

record_server_online(addr)

Set a gauge indicating the server is online.

record_solve(team=None, attempts_until=None, seconds_to=None)

Record a successful solve including timing/counter metadata.

configure_logging_and_metrics(ctf_slug, service, logger_name='ctf.common')

Configure the shared logger and return a metrics helper.

The helper ensures that every challenge server emits consistent, structured log lines and exposes a Metrics wrapper for pushing Prometheus gauges and counters. Call it exactly once during process startup before any background tasks are spawned so that the Loki handler thread and metric registry stay process-wide singletons.

Parameters:

Name	Type	Description	Default
ctf_slug	str	Challenge identifier used to label log and metric streams.	required
service	str	Name of the running service, e.g. "server" or "solver".	required
logger_name	str	Optional logger name; defaults to "ctf.common" which works for most services.	'ctf.common'