Skip to content

FastStream Prometheus: use the default registry and make the metrics path opt-in #321

Closed

Description

@lesnik512

FastStream is the only bootstrapper that serves a private registry: FastStreamPrometheusInstrument builds a fresh CollectorRegistry unless prometheus_collector_registry is set (lite_bootstrap/bootstrappers/faststream_bootstrapper.py:188-203), while FastAPI, Litestar and FastMCP use prometheus_client.REGISTRY (docs/introduction/configuration.md:86-88). Collectors a FastStream service registers the usual way never reach its /metrics.

It is also the only one whose Prometheus instrument needs more than a path to be configured. prometheus_metrics_path defaults to "/metrics" (lite_bootstrap/instruments/prometheus_instrument.py:12), so is_configured additionally requires prometheus_middleware_cls or prometheus_collector_registry (faststream_bootstrapper.py:205-210). #229 listed defaulting the path to "" on FastStream and deleting that override as the cleanest rule, and set it aside only because it is breaking.

Work

  • Test first, both failing today:
    • a FastStreamConfig with prometheus_middleware_cls and no prometheus_metrics_path skips the Prometheus instrument with the base reason ("prometheus_metrics_path is empty or not valid");
    • with a path set and no injected registry, the instrument's collector_registry is prometheus_client.REGISTRY.
  • Override prometheus_metrics_path: str = "" on FastStreamConfig and delete the is_configured override, along with the extended not_configured_reason at :195-198.
  • Default the registry to prometheus_client.REGISTRY and delete _make_collector_registry. Keep prometheus_collector_registry as the way to pass a private one.
  • A second bootstrap in one process needs no reuse code, unlike FastMCP's tool-call collectors (lite_bootstrap/bootstrappers/fastmcp_bootstrapper.py:89-104): FastStream's MetricsContainer looks up existing collectors in the registry before creating them (faststream/prometheus/container.py:188-189 in 0.7.4), and two RedisPrometheusMiddleware(registry=REGISTRY) instances construct without error. Pin the multi-broker case from fix: instrument every FastStream broker, with per-type middleware classes #299 in a test.
  • Docs: docs/introduction/configuration.md:70-88 and docs/integrations/faststream.md.

Verify: the new tests pass, and a FastStream app with prometheus_metrics_path="/metrics" and a broker middleware serves the broker metrics plus the default process and platform collectors.

Breaking for FastStream services that set only prometheus_middleware_cls: /metrics stops being mounted until they set prometheus_metrics_path. Services that scrape it see the default collectors and anything else on the global registry in addition to the broker metrics.

Activity

  1. added this to the 2.0.0 milestone on Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestneeds-triageMaintainer needs to evaluate this issue

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions