feat: rename inconsistent config fields, keeping the old names as deprecated aliases (#351)

* feat: rename inconsistent config fields, keeping the old names as deprecated aliases

* docs: say which OpenAPIConfig arguments swagger_additional_params cannot repeat

Author: lesnik512

benchmarks/README.md

@@ -200,7 +200,7 @@ structlog 26.1.0. In-process, baseline 17.7 µs per request. The handler does no
 | scenario | +µs/req | note |
 |---|---:|---|
 | logging configured, no records | +0.1 | |
-| `fastapi_logging_middleware_enabled=True` | +18.3 | one access-log record per request, about 10 µs of it the record |
+| `logging_access_log_enabled=True` | +18.3 | one access-log record per request, about 10 µs of it the record |
 | Prometheus | +19.1 | |
 | OpenTelemetry, 100% sampling | +147.9 | |
 | OpenTelemetry, `opentelemetry_exclude_spans=["receive", "send"]` | +101.6 | -46.3 |
@@ -354,7 +354,7 @@ prometheus-client 0.26.0, structlog 26.1.0. In-process, baseline 12.1 µs per re
 |---|---:|---|
 | logging configured, no records | -0.1 | free until something logs |
 | logging, 3 structlog records in the handler | +33.8 | 11.3 µs per record |
-| `litestar_logging_middleware_enabled=True` | +70.7 | 2 records per request, each written twice; a second run gave +74.4 |
+| `logging_access_log_enabled=True` | +70.7 | 2 records per request, each written twice; a second run gave +74.4 |
 | Prometheus | +11.6 | |
 | Prometheus, `prometheus_group_path=False` | +11.8 | |
 | OpenTelemetry, 100% sampling | +145.4 | a second run gave +131.8 |
@@ -477,7 +477,7 @@ it FastMCP and the MCP SDK. Noise on this suite is about ±30 µs even with 3 re
 | scenario | +µs/call | note |
 |---|---:|---|
 | logging configured | +15 | noise |
-| `fastmcp_logging_middleware_enabled=True` | +51 | one record per MCP message |
+| `logging_access_log_enabled=True` | +51 | one record per MCP message |
 | Prometheus (HTTP instrumentator and tool-call middleware) | +35 | the split between the two is within noise |
 | OpenTelemetry, 100% | +272 | 3 ASGI spans plus FastMCP's own server span |
 | OpenTelemetry, 100%, FastMCP's own spans replaced by a no-op tracer | +226 | FastMCP's spans cost 46 |

benchmarks/frameworks/fastapi_suite.py

@@ -31,7 +31,7 @@
 SCENARIOS: typing.Final = {
     "bare": Scenario(config=base_config()),
     "log": Scenario(config=base_config(**LOG)),
-    "log_mw": Scenario(config=base_config(**LOG, fastapi_logging_middleware_enabled=True)),
+    "log_mw": Scenario(config=base_config(**LOG, logging_access_log_enabled=True)),
     "prom": Scenario(config=base_config(**PROM)),
     "otel": Scenario(config=base_config(**OTEL)),
     "otel_excl": Scenario(config=base_config(**OTEL, **EXCL)),

benchmarks/frameworks/fastmcp_suite.py

@@ -41,7 +41,7 @@ def no_fastmcp_spans() -> None:
 SCENARIOS: typing.Final = {
     "bare": Scenario(config=base_config()),
     "log": Scenario(config=base_config(**LOG)),
-    "log_mw": Scenario(config=base_config(**LOG, fastmcp_logging_middleware_enabled=True)),
+    "log_mw": Scenario(config=base_config(**LOG, logging_access_log_enabled=True)),
     "prom": Scenario(config=base_config(**PROM)),
     "otel": Scenario(config=base_config(**OTEL)),
     "otel_nofastmcp_spans": Scenario(config=base_config(**OTEL), patch=no_fastmcp_spans),

benchmarks/frameworks/litestar_suite.py

@@ -45,7 +45,7 @@
     "defaults_noobs": Scenario(config=base_config(**LITESTAR_DEFAULTS)),
     "log": Scenario(config=base_config(**LOG)),
     "log_log3": Scenario(config=base_config(**LOG), kind="structlog"),
-    "log_mw": Scenario(config=base_config(**LOG, litestar_logging_middleware_enabled=True)),
+    "log_mw": Scenario(config=base_config(**LOG, logging_access_log_enabled=True)),
     "prom": Scenario(config=base_config(**PROM)),
     "prom_nogroup": Scenario(config=base_config(**PROM, prometheus_group_path=False)),
     "otel": Scenario(config=base_config(**OTEL)),

docs/integrations/fastapi.md

@@ -58,7 +58,7 @@ place to add a log record. Turn it on explicitly:
 ```python
 FastAPIConfig(
     service_name="microservice",
-    fastapi_logging_middleware_enabled=True,
+    logging_access_log_enabled=True,
 )
 ```
 
@@ -81,7 +81,7 @@ structured one, clear uvicorn's handlers:
 ```python
 FastAPIConfig(
     service_name="microservice",
-    fastapi_logging_middleware_enabled=True,
+    logging_access_log_enabled=True,
     logging_unset_handlers=["uvicorn.access"],
 )
 ```

docs/integrations/fastmcp.md

@@ -55,7 +55,7 @@ explicitly:
 ```python
 FastMcpConfig(
     service_name="microservice",
-    fastmcp_logging_middleware_enabled=True,
+    logging_access_log_enabled=True,
 )
 ```
 

docs/integrations/litestar.md

@@ -68,7 +68,7 @@ Swagger bundle into your logs. Turn it on explicitly:
 ```python
 LitestarConfig(
     service_name="microservice",
-    litestar_logging_middleware_enabled=True,
+    logging_access_log_enabled=True,
 )
 ```
 
@@ -92,7 +92,7 @@ from litestar.middleware.logging import LoggingMiddlewareConfig
 
 LitestarConfig(
     service_name="microservice",
-    litestar_logging_middleware_enabled=True,
+    logging_access_log_enabled=True,
     litestar_logging_middleware_config=LoggingMiddlewareConfig(request_log_fields=("path", "method", "content_type")),
 )
 ```

docs/introduction/configuration.md

@@ -93,9 +93,9 @@ Prometheus's integration for FastAPI uses `prometheus_fastapi_instrumentator` pa
 
 Additional parameters for FastAPI integration:
 
-- `prometheus_instrumentator_params` - passed to `prometheus_fastapi_instrumentator.Instrumentator`
-- `prometheus_instrument_params` - passed to `method Instrumentator(...).instrument`
-- `prometheus_expose_params` - passed to `method Instrumentator(...).expose`.
+- `prometheus_instrumentator_additional_params` - passed to `prometheus_fastapi_instrumentator.Instrumentator`
+- `prometheus_instrument_additional_params` - passed to `method Instrumentator(...).instrument`
+- `prometheus_expose_additional_params` - passed to `method Instrumentator(...).expose`.
 
 ### Prometheus FastMCP
 
@@ -110,9 +110,9 @@ route itself is not counted. Tool calls are counted in `fastmcp_tool_calls_total
 
 Additional parameters for FastMCP integration:
 
-- `prometheus_instrumentator_params` - passed to `prometheus_fastapi_instrumentator.Instrumentator`;
+- `prometheus_instrumentator_additional_params` - passed to `prometheus_fastapi_instrumentator.Instrumentator`;
   `excluded_handlers` defaults to the metrics route.
-- `prometheus_instrument_params` - passed to `method Instrumentator(...).instrument`.
+- `prometheus_instrument_additional_params` - passed to `method Instrumentator(...).instrument`.
 - `fastmcp_prometheus_tool_metrics_enabled` - count and time tool calls (default: `True`).
 
 
@@ -321,16 +321,16 @@ async def handler(request: Request) -> dict[str, str]:
 
 Additional parameters for Litestar's access-log middleware:
 
-- `litestar_logging_middleware_enabled` - turn on request/response access logging (default: `False`).
-- `litestar_logging_middleware_config` - a caller-supplied `LoggingMiddlewareConfig` that replaces the built-in defaults wholesale. It is ignored, with a warning, unless `litestar_logging_middleware_enabled` is `True`.
+- `logging_access_log_enabled` - turn on request/response access logging (default: `False`).
+- `litestar_logging_middleware_config` - a caller-supplied `LoggingMiddlewareConfig` that replaces the built-in defaults wholesale. It is ignored, with a warning, unless `logging_access_log_enabled` is `True`.
 
 See [the Litestar integration guide](../integrations/litestar.md#logging) for what gets logged and why access logging defaults to off.
 
 ### Structlog FastAPI
 
 FastAPI ships no access log of its own, so lite-bootstrap provides one. It is **off by default**:
 
-- `fastapi_logging_middleware_enabled` - turn on the structured access log (default: `False`).
+- `logging_access_log_enabled` - turn on the structured access log (default: `False`).
 
 See [the FastAPI integration guide](../integrations/fastapi.md#logging) for what gets logged and why
 it defaults to off.
@@ -339,7 +339,7 @@ it defaults to off.
 
 The per-MCP-message access log is **off by default**:
 
-- `fastmcp_logging_middleware_enabled` - turn on the access log (default: `False`).
+- `logging_access_log_enabled` - turn on the access log (default: `False`).
 
 See [the FastMCP integration guide](../integrations/fastmcp.md#logging) for what gets logged.
 
@@ -383,6 +383,7 @@ To bootstrap swagger, you have the following parameters:
 - `swagger_static_path` - path for offline docs static
 - `swagger_path`
 - `swagger_offline_docs` - option to turn on offline docs.
+- `swagger_additional_params` - Litestar only: extra keyword arguments for `litestar.openapi.OpenAPIConfig`. It cannot repeat `path`, `title`, `version`, `description` or `render_plugins`, which lite-bootstrap already passes.
 
 Swagger is on by default at `swagger_path` (default: `/docs`). For Litestar, set `swagger_path` to an empty string to disable it.
 

docs/introduction/performance.md

@@ -59,7 +59,7 @@ so there is nothing else material hiding in it. That configuration is:
 --8<-- "benchmarks/README.md:tuned"
 
 One thing to leave off rather than turn on: the FastAPI access log
-([`fastapi_logging_middleware_enabled`](../integrations/fastapi.md#logging)) is off by default, and
+([`logging_access_log_enabled`](../integrations/fastapi.md#logging)) is off by default, and
 turning it on makes every request emit a log record. On a service that otherwise logs nothing per
 request, every request then pays the per-record cost measured here:
 
@@ -102,7 +102,7 @@ The same app on Granian, over real sockets:
 
 **Sentry costs more on Litestar than on FastAPI**, and all of it is `LitestarIntegration`: turning
 off auto-enabling integrations removes the cost and, with it, request error capture. The access log
-([`litestar_logging_middleware_enabled`](../integrations/litestar.md#logging)) is the other large opt-in
+([`logging_access_log_enabled`](../integrations/litestar.md#logging)) is the other large opt-in
 item, at about 70 µs per request in-process.
 
 ## FastStream

lite_bootstrap/bootstrappers/fastapi_bootstrapper.py

@@ -2,7 +2,7 @@
 import dataclasses
 import time
 import typing
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Mapping
 
 from lite_bootstrap import import_checker
 from lite_bootstrap.bootstrappers.base import BaseBootstrapper
@@ -63,10 +63,27 @@ class FastAPIConfig(
     application_kwargs: dict[str, typing.Any] = dataclasses.field(default_factory=dict)
     # Not on OpenTelemetryConfig: only the FastAPI and Litestar instrumentors take `exclude_spans`.
     opentelemetry_exclude_spans: list[typing.Literal["receive", "send"]] = dataclasses.field(default_factory=list)
-    prometheus_instrumentator_params: dict[str, typing.Any] = dataclasses.field(default_factory=dict)
-    prometheus_instrument_params: dict[str, typing.Any] = dataclasses.field(default_factory=dict)
-    prometheus_expose_params: dict[str, typing.Any] = dataclasses.field(default_factory=dict)
-    fastapi_logging_middleware_enabled: bool = False
+    prometheus_instrumentator_additional_params: dict[str, typing.Any] = dataclasses.field(default_factory=dict)
+    prometheus_instrument_additional_params: dict[str, typing.Any] = dataclasses.field(default_factory=dict)
+    prometheus_expose_additional_params: dict[str, typing.Any] = dataclasses.field(default_factory=dict)
+    logging_access_log_enabled: bool = False
+    # Deprecated names, removed in 2.0.
+    _renamed_fields: typing.ClassVar[Mapping[str, str]] = {
+        "prometheus_instrumentator_params": "prometheus_instrumentator_additional_params",
+        "prometheus_instrument_params": "prometheus_instrument_additional_params",
+        "prometheus_expose_params": "prometheus_expose_additional_params",
+        "fastapi_logging_middleware_enabled": "logging_access_log_enabled",
+    }
+    prometheus_instrumentator_params: dict[str, typing.Any] | UnsetType = dataclasses.field(
+        default=UNSET, repr=False, compare=False
+    )
+    prometheus_instrument_params: dict[str, typing.Any] | UnsetType = dataclasses.field(
+        default=UNSET, repr=False, compare=False
+    )
+    prometheus_expose_params: dict[str, typing.Any] | UnsetType = dataclasses.field(
+        default=UNSET, repr=False, compare=False
+    )
+    fastapi_logging_middleware_enabled: bool | UnsetType = dataclasses.field(default=UNSET, repr=False, compare=False)
 
     def __post_init__(self) -> None:
         # @dataclass(slots=True) replaces the class object, breaking bare super().
@@ -158,7 +175,7 @@ async def send_wrapper(message: "Message") -> None:
 class FastAPILoggingInstrument(LoggingInstrument[FastAPIConfig]):
     def bootstrap(self) -> None:
         super().bootstrap()
-        if not self.bootstrap_config.fastapi_logging_middleware_enabled:
+        if not self.bootstrap_config.logging_access_log_enabled:
             return
         self.bootstrap_config.app.add_middleware(_AccessLogMiddleware, excluded_paths=self._build_excluded_paths())
 
@@ -218,14 +235,14 @@ def dependencies_installed() -> bool:
     def bootstrap(self) -> None:
         config = self.bootstrap_config
         application = config.app
-        Instrumentator(**config.prometheus_instrumentator_params).instrument(
+        Instrumentator(**config.prometheus_instrumentator_additional_params).instrument(
             application,
-            **config.prometheus_instrument_params,
+            **config.prometheus_instrument_additional_params,
         ).expose(
             application,
             endpoint=config.prometheus_metrics_path,
             include_in_schema=config.prometheus_metrics_include_in_schema,
-            **config.prometheus_expose_params,
+            **config.prometheus_expose_additional_params,
         )