Skip to content

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

Merged
lesnik512 merged 1 commit into
mainfrom
faststream-prometheus-default-registry
Oct 29, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
faststream-prometheus-default-registry

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Closes #321.

FastStream's Prometheus instrument now follows the same rule as FastAPI, Litestar and FastMCP: it serves prometheus_client.REGISTRY and is configured by its path alone. The path now defaults to empty, so on FastStream the endpoint is opt-in.

  • FastStreamConfig overrides prometheus_metrics_path: str = "".
  • FastStreamPrometheusInstrument no longer overrides is_configured or extends not_configured_reason. A config with no path is skipped with the base reason, "prometheus_metrics_path is empty or not valid".
  • With no prometheus_collector_registry, the instrument uses prometheus_client.REGISTRY, and _make_collector_registry is gone. prometheus_collector_registry is still how you pass a private registry.

A second bootstrap, or several brokers, on the global registry needs no reuse code. faststream's MetricsContainer looks up a collector in the registry before creating one, and it already did at our 0.6 floor (faststream/prometheus/container.py in 0.6.0 and 0.7.8).

Tests

Written first. These failed on main:

  • test_faststream_prometheus_is_skipped_without_metrics_path: with prometheus_middleware_cls set and no path, the instrument was configured.
  • test_faststream_prometheus_serves_the_default_registry: with a path and neither a middleware nor a registry, the instrument was skipped. It now asserts that collector_registry is prometheus_client.REGISTRY, and that /metrics serves a counter registered on the default registry plus python_info from the default platform collector.

test_faststream_default_registry_takes_two_brokers_and_a_second_bootstrap pins the multi-broker case from #299. It bootstraps two Redis brokers with RedisPrometheusMiddleware on the default registry, twice in one process, and checks that each broker gets its middleware. It passed on main too, where every bootstrap built a fresh registry.

These replace test_faststream_prometheus_is_skipped_without_middleware_or_registry, which asserted the rule this PR removes.

The full suite passes, 590 tests at 100% coverage (just test-ci). just lint (including ty), just adr-check and just docs-build pass too. No floor changes.

Docs

  • configuration.md: the Prometheus intro notes the FastStream exception, and "Prometheus FastStream" describes the empty default and the default registry. The paragraph explaining the private registry is gone.
  • faststream.md: the multiple-brokers example sets prometheus_metrics_path. Without it, under the new default, its Prometheus middleware would be skipped.

Breaking changes

  • If your FastStream service sets only prometheus_middleware_cls, /metrics is no longer mounted and the broker middleware is no longer added until you set prometheus_metrics_path.
  • Scrapes now also return the default process and platform collectors, and anything else on the global registry, alongside the broker metrics.

@lesnik512 lesnik512 added this to the 2.0.0 milestone Oct 29, 2026
@lesnik512
lesnik512 merged commit 182c357 into main Oct 29, 2026
37 checks passed
@lesnik512
lesnik512 deleted the faststream-prometheus-default-registry branch October 29, 2026 16:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant