Pluggable web frameworks, OpenTelemetry tracing, and web feature flags

CHANGELOG.md

@@ -11,6 +11,54 @@ https://github.com/faust-streaming/faust/releases.  The v0.12.0 entry below
 resumes the Keep a Changelog format.
 -->
 
+## [Unreleased]
+
+### Added
+- Per-endpoint feature flags for the built-in web endpoints:
+  `web_stats_enabled`, `web_graph_enabled`, `web_router_enabled`,
+  `web_tables_enabled` and `web_metrics_enabled`. Previously `debug` was the
+  only control, and it enabled the statistics and graph endpoints together,
+  while `/router` and `/table` could not be turned off at all — even though
+  `/table` serves table *data* over HTTP. The statistics and graph flags take
+  their default from `debug`, so behaviour is unchanged unless you set them.
+- New `/performance/` endpoint (`web_metrics_enabled`, off by default)
+  returning throughput, latency percentiles, consumer lag and table statistics
+  as JSON. Consumer lag and latency percentiles are computed here — `Monitor`
+  tracks read and log-end offsets but never derives lag, and keeps raw latency
+  deques rather than summaries. Needs no extra dependency, and is independent
+  of both `debug` and `faust.sensors.prometheus`. Custom frameworks can expose
+  the same payload with `faust.sensors.metrics.performance_metrics()`.
+- Framework-neutral web servers: `App.web_server()` accepts any `mode.Service`
+  as a replacement for the legacy `faust.web`/aiohttp stack. The custom server
+  starts after table recovery and obeys `web_enabled`/`--without-web`.
+- `faust.contrib.asgi`: co-host any ASGI application with the worker, in one
+  process and one event loop. `faust_lifespan()` runs Faust from an ASGI
+  lifespan; `FaustLifespanMiddleware` supplies lifespan support to Django and
+  other ASGI applications without a lifespan hook; `serve_asgi()` installs the
+  ASGI app as the worker's only web server. New `faust[asgi]` extra;
+  `faust[fastapi]` adds FastAPI as well.
+- `faust.contrib.opentelemetry`: OpenTelemetry tracing. `setup_opentelemetry()`
+  continues a trace from Kafka message headers into your agents — the hop
+  `opentelemetry-instrumentation-aiokafka` cannot bridge, because Faust's
+  consumer runs in its own thread. FastAPI apps are instrumented automatically
+  when an SDK is configured. New `faust[opentelemetry]` extra.
+- New userguide page: *FastAPI and other ASGI applications*.
+
+### Fixed
+- Faust apps no longer resolve an event loop when agents, tables or the
+  transport are declared at import time. Previously that pinned the app to a
+  loop that was never run, so starting it from `asyncio.run()` — as uvicorn
+  does — failed with "Please create objects with the same loop as running with"
+  or "Task ... got Future ... attached to a different loop" (#322, #435, #448).
+- `faust[aerospike]` installed nothing: `requirements/extras/aerospike.txt`
+  shipped without the matching `BUNDLES` entry in `setup.py`, despite being
+  advertised in the README. A new test guards both directions of that mapping.
+
+### Changed
+- The `examples/fastapi/` directory is now `examples/fastapi_project/`. The old
+  name shadowed the real `fastapi` package when running the sibling
+  `examples/fastapi_example.py`, so neither example could be run as documented.
+
 ## [v0.12.1](https://github.com/faust-streaming/faust/releases/tag/v0.12.1) - 2026-07-19
 
 [Compare with v0.12.0](https://github.com/faust-streaming/faust/compare/v0.12.0...v0.12.1)

docs/includes/installation.txt

@@ -91,6 +91,26 @@ Sensors
 :``faust[sentry]``:
     for reporting worker errors to Sentry via :pypi:`sentry-sdk`.
 
+:``faust[opentracing]``:
+    for distributed tracing via :pypi:`opentracing`.  Deprecated upstream in
+    March 2026; prefer ``faust[opentelemetry]`` for new work.
+
+:``faust[opentelemetry]``:
+    for distributed tracing via :pypi:`opentelemetry-api`, including
+    continuing a trace from Kafka message headers into your agents.  See
+    :ref:`guide-asgi`.
+
+Web
+~~~
+
+:``faust[asgi]``:
+    for serving any ASGI application as the worker's web application, via
+    :pypi:`uvicorn`.  See :ref:`guide-asgi`.
+
+:``faust[fastapi]``:
+    installs the ASGI integration plus :pypi:`fastapi`.
+    See :ref:`guide-asgi`.
+
 Event Loops
 ~~~~~~~~~~~
 

docs/includes/settingref.txt

@@ -1957,7 +1957,42 @@ Advanced Web Server Settings
 :type: :class:`str` / :class:`~yarl.URL`
 :default: ``'aiohttp://'``
 
-Web server driver to use.
+Legacy :mod:`faust.web` driver to use. This setting is ignored when the
+application registers a framework-neutral server with
+:meth:`faust.App.web_server`.
+
+.. setting:: web_application_options
+
+``web_application_options``
+---------------------------
+
+.. versionadded:: 0.11.4
+
+:type: :class:`~typing.Mapping` [ :class:`str`, :class:`~typing.Any` ]
+:default: :const:`None`
+
+Extra keyword arguments passed to the web framework's application.
+
+Use this to configure the underlying web application object that the
+web driver creates.  For the default :pypi:`aiohttp` driver these are
+forwarded straight to :class:`aiohttp.web.Application`, so you can set
+things like ``client_max_size`` or install middlewares:
+
+.. sourcecode:: python
+
+    from aiohttp.web import middleware
+
+    @middleware
+    async def error_middleware(request, handler):
+        ...
+
+    app = App(..., web_application_options={
+        'client_max_size': 1024 ** 2 * 20,
+        'middlewares': [error_middleware],
+    })
+
+The accepted keys depend on the configured web driver.
+
 
 .. setting:: web_bind
 
@@ -2039,6 +2074,132 @@ Enable web server and other web components.
 This option can also be set using :option:`faust worker --without-web`.
 
 
+.. setting:: web_graph_enabled
+
+``web_graph_enabled``
+---------------------
+
+.. versionadded:: 0.15.0
+
+:type: :class:`bool`
+:default (alias to setting): :setting:`debug`
+:environment: :envvar:`APP_WEB_GRAPH_ENABLED`
+
+Enable/disable the ``/graph`` dependency graph endpoint.
+
+Renders the worker's service dependency graph as a PNG.
+
+If not set, this follows :setting:`debug`, which is how this endpoint
+was gated before this setting existed.
+
+.. warning::
+
+    The graph describes the entire internal service tree of the
+    worker.
+
+
+.. setting:: web_metrics_enabled
+
+``web_metrics_enabled``
+-----------------------
+
+.. versionadded:: 0.15.0
+
+:type: :class:`bool`
+:default: :const:`False`
+:environment: :envvar:`APP_WEB_METRICS_ENABLED`
+
+Enable/disable the ``/performance/`` metrics endpoint.
+
+Serves throughput, latency, consumer lag and table statistics as
+JSON, gathered from :setting:`Monitor`.  Unlike the statistics
+endpoints this is independent of :setting:`debug`, so it can be left
+on in production.
+
+Disabled by default: it is a new endpoint, and enabling it should be
+a deliberate choice.
+
+.. seealso::
+
+    :mod:`faust.sensors.prometheus` serves the same underlying data
+    in Prometheus format on its own ``/metrics`` path.
+
+
+.. setting:: web_router_enabled
+
+``web_router_enabled``
+----------------------
+
+.. versionadded:: 0.15.0
+
+:type: :class:`bool`
+:default: :const:`True`
+:environment: :envvar:`APP_WEB_ROUTER_ENABLED`
+
+Enable/disable the ``/router`` endpoints.
+
+These report which worker in the cluster owns a given table key, and
+are what makes :meth:`@table_route` work across nodes.
+
+.. warning::
+
+    Disabling this breaks :meth:`@table_route` for multi-node
+    deployments.  Only turn it off if you route entirely within a
+    single worker.
+
+    Left enabled, it exposes your cluster topology -- the URLs of
+    every other worker.
+
+
+.. setting:: web_stats_enabled
+
+``web_stats_enabled``
+---------------------
+
+.. versionadded:: 0.15.0
+
+:type: :class:`bool`
+:default (alias to setting): :setting:`debug`
+:environment: :envvar:`APP_WEB_STATS_ENABLED`
+
+Enable/disable the built-in statistics endpoints.
+
+Serves sensor statistics at ``/`` and the current partition
+assignment at ``/assignment/``.
+
+If not set, this follows :setting:`debug`, which is how these
+endpoints were gated before this setting existed.
+
+When disabled, ``/`` serves the plain production index instead.
+
+.. warning::
+
+    These endpoints expose internal state: every registered sensor's
+    counters, and which partitions this worker is handling.
+
+
+.. setting:: web_tables_enabled
+
+``web_tables_enabled``
+----------------------
+
+.. versionadded:: 0.15.0
+
+:type: :class:`bool`
+:default: :const:`True`
+:environment: :envvar:`APP_WEB_TABLES_ENABLED`
+
+Enable/disable the ``/table`` endpoints.
+
+These list the tables defined by this app and allow reading
+individual keys over HTTP.
+
+.. warning::
+
+    This exposes table *data*, not just table names.  If your tables
+    hold anything sensitive, turn this off.
+
+
 .. setting:: web_host
 
 ``web_host``

docs/reference/faust.contrib.asgi.rst

@@ -0,0 +1,9 @@
+=====================================================
+ ``faust.contrib.asgi``
+=====================================================
+
+.. currentmodule:: faust.contrib.asgi
+
+.. automodule:: faust.contrib.asgi
+    :members:
+    :undoc-members:

docs/reference/faust.contrib.fastapi.rst

@@ -0,0 +1,14 @@
+=====================================================
+ ``faust.contrib.fastapi``
+=====================================================
+
+Compatibility alias for :mod:`faust.contrib.asgi`. New code should import the
+framework-neutral module directly.
+
+.. contents::
+    :local:
+.. currentmodule:: faust.contrib.fastapi
+
+.. automodule:: faust.contrib.fastapi
+    :members:
+    :undoc-members:

docs/reference/faust.contrib.opentelemetry.rst

@@ -0,0 +1,11 @@
+=====================================================
+ ``faust.contrib.opentelemetry``
+=====================================================
+
+.. contents::
+    :local:
+.. currentmodule:: faust.contrib.opentelemetry
+
+.. automodule:: faust.contrib.opentelemetry
+    :members:
+    :undoc-members:

docs/reference/faust.sensors.metrics.rst

@@ -0,0 +1,11 @@
+=====================================================
+ ``faust.sensors.metrics``
+=====================================================
+
+.. contents::
+    :local:
+.. currentmodule:: faust.sensors.metrics
+
+.. automodule:: faust.sensors.metrics
+    :members:
+    :undoc-members:

docs/reference/faust.web.apps.metrics.rst

@@ -0,0 +1,11 @@
+=====================================================
+ ``faust.web.apps.metrics``
+=====================================================
+
+.. contents::
+    :local:
+.. currentmodule:: faust.web.apps.metrics
+
+.. automodule:: faust.web.apps.metrics
+    :members:
+    :undoc-members:

docs/reference/index.rst

@@ -54,6 +54,9 @@ Contrib
     :maxdepth: 1
 
     faust.contrib
+    faust.contrib.asgi
+    faust.contrib.fastapi
+    faust.contrib.opentelemetry
     faust.contrib.sentry
 
 Fixups
@@ -104,6 +107,7 @@ Sensors
     faust.sensors
     faust.sensors.base
     faust.sensors.datadog
+    faust.sensors.metrics
     faust.sensors.monitor
     faust.sensors.otel
     faust.sensors.prometheus
@@ -242,6 +246,7 @@ Web
     :maxdepth: 1
 
     faust.web.apps.graph
+    faust.web.apps.metrics
     faust.web.apps.router
     faust.web.apps.stats
     faust.web.base