metrics

metrics

Prometheus metrics collection and HTTP exposition.

Defines module-level metric objects (singletons, thread-safe) that are shared across all services. BaseService.run_forever() automatically records cycle counts, durations, and failure streaks. Services add custom metrics through set_gauge() and inc_counter() on the base class.

The MetricsServer provides an async HTTP endpoint (via aiohttp) for Prometheus scraping. Configuration is handled through MetricsConfig, which can be embedded in any service's YAML configuration via BaseServiceConfig.

Attributes:

• SERVICE_INFO –

  Static metadata set once at startup.

• SERVICE_GAUGE –

  Point-in-time values (current state).

• SERVICE_COUNTER –

  Cumulative totals (monotonically increasing).

• CYCLE_DURATION_SECONDS –

  Histogram for latency percentiles (p50/p95/p99).

See Also

BaseService: Automatically records metrics during run_forever(). BaseServiceConfig: Embeds MetricsConfig for per-service metrics configuration.

Classes

MetricsConfig

Bases: BaseModel

Configuration for the Prometheus metrics endpoint.

Set host to "0.0.0.0" in container environments to allow external scraping. The endpoint is only started when enabled is True.

See Also

MetricsServer: HTTP server that consumes this configuration. BaseServiceConfig: Parent configuration that embeds this model.

MetricsServer

MetricsServer(config: MetricsConfig)

Async HTTP server exposing a Prometheus-compatible /metrics endpoint.

Built on aiohttp for compatibility with the async service architecture. The endpoint path is configurable via MetricsConfig.path.

Examples:

server = MetricsServer(MetricsConfig(port=8001))
await server.start()
# ... service runs ...
await server.stop()

See Also

MetricsConfig: Configuration model controlling host, port, path, and enabled state. start_metrics_server(): Convenience function that creates and starts a server in one call. BaseService: Service base class that records metrics consumed by this endpoint.

Source code in src/bigbrotr/core/metrics.py

def __init__(self, config: MetricsConfig) -> None:
    self._config = config
    self._runner: web.AppRunner | None = None

Functions

start async

start() -> None

Start listening for Prometheus scrape requests.

Returns immediately (no-op) if metrics are disabled in the MetricsConfig. Otherwise, binds an aiohttp server to the configured host and port.

Raises:

• OSError –

  If the port is already in use or binding fails.

See Also

stop(): Shut down the server and release the bound port.

Source code in src/bigbrotr/core/metrics.py

async def start(self) -> None:
    """Start listening for Prometheus scrape requests.

    Returns immediately (no-op) if metrics are disabled in the
    [MetricsConfig][bigbrotr.core.metrics.MetricsConfig]. Otherwise,
    binds an aiohttp server to the configured host and port.

    Raises:
        OSError: If the port is already in use or binding fails.

    See Also:
        [stop()][bigbrotr.core.metrics.MetricsServer.stop]: Shut down
            the server and release the bound port.
    """
    if not self._config.enabled:
        return

    app = web.Application()
    app.router.add_get(self._config.path, self._handle_metrics)

    self._runner = web.AppRunner(app, access_log=None)
    await self._runner.setup()

    site = web.TCPSite(
        self._runner,
        self._config.host,
        self._config.port,
    )
    await site.start()

stop async

stop() -> None

Stop the HTTP server and release resources.

Idempotent: safe to call if the server was never started or has already been stopped.

Source code in src/bigbrotr/core/metrics.py

async def stop(self) -> None:
    """Stop the HTTP server and release resources.

    Idempotent: safe to call if the server was never started or
    has already been stopped.
    """
    if self._runner:
        await self._runner.cleanup()
        self._runner = None

Functions

start_metrics_server async

start_metrics_server(
    config: MetricsConfig | None = None,
) -> MetricsServer

Convenience function to create and start a metrics server.

Parameters:

• config (MetricsConfig | None, default: None ) –

  MetricsConfig instance. Uses defaults if not provided.

Returns:

• MetricsServer –

  A running MetricsServer

• MetricsServer –

  instance. Caller should call

• MetricsServer –

  stop() during

• MetricsServer –

  shutdown to release the bound port.

See Also

MetricsServer: The server class instantiated by this function.

Source code in src/bigbrotr/core/metrics.py

async def start_metrics_server(
    config: MetricsConfig | None = None,
) -> MetricsServer:
    """Convenience function to create and start a metrics server.

    Args:
        config: [MetricsConfig][bigbrotr.core.metrics.MetricsConfig]
            instance. Uses defaults if not provided.

    Returns:
        A running [MetricsServer][bigbrotr.core.metrics.MetricsServer]
        instance. Caller should call
        [stop()][bigbrotr.core.metrics.MetricsServer.stop] during
        shutdown to release the bound port.

    See Also:
        [MetricsServer][bigbrotr.core.metrics.MetricsServer]: The server
            class instantiated by this function.
    """
    config = config or MetricsConfig()
    server = MetricsServer(config)
    await server.start()
    return server