fastapi-observer 1.6.0__tar.gz → 1.8.0__tar.gz

{fastapi_observer-1.6.0/src/fastapi_observer.egg-info → fastapi_observer-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 1.6.0
+Version: 1.8.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -147,7 +147,7 @@ Explicit variables and Python arguments always win over profile defaults. Every
 ## What you get
 
 - **One JSON line per request** with method, path, status, duration and client IP, and your service's name, environment and version on every line, including your own `logging` calls.
-- **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, and returned in the response.
+- **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, returned in the response and passed on to the services you call, so one ID finds a request's logs in every service.
 - **Redaction on by default.** Passwords, tokens, API keys, `Authorization` and cookies are masked before anything is written. Presets cover stricter needs (`strict`, `pci`, `gdpr`).
 - **Prometheus metrics** labelled by route template (`/orders/{order_id}`), so URLs with IDs don't explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
@@ -186,7 +186,7 @@ What it costs: with default settings, about 43 µs of CPU per request on an Appl
 
 ## Why you can trust it
 
-- Tested in CI on Python 3.11 to 3.15, fully typed, and used in production by its maintainer.
+- Tested in CI on Python 3.11 to 3.15, type-checked with `mypy --strict`, tested nightly against the newest OpenTelemetry releases, and used in production by its maintainer.
 - Releases are published with PyPI Trusted Publishing and signed attestations. CI runs `pip-audit` and generates an SBOM.
 - Security fixes are called out in the [changelog](https://github.com/Vitaee/FastapiObserver/blob/main/CHANGELOG.md). To report a vulnerability, see [SECURITY.md](https://github.com/Vitaee/FastapiObserver/blob/main/SECURITY.md).
 - Benchmarks are reproducible from [`examples/benchmarks`](https://github.com/Vitaee/FastapiObserver/tree/main/examples/benchmarks).

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/README.md

@@ -71,7 +71,7 @@ Explicit variables and Python arguments always win over profile defaults. Every
 ## What you get
 
 - **One JSON line per request** with method, path, status, duration and client IP, and your service's name, environment and version on every line, including your own `logging` calls.
-- **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, and returned in the response.
+- **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, returned in the response and passed on to the services you call, so one ID finds a request's logs in every service.
 - **Redaction on by default.** Passwords, tokens, API keys, `Authorization` and cookies are masked before anything is written. Presets cover stricter needs (`strict`, `pci`, `gdpr`).
 - **Prometheus metrics** labelled by route template (`/orders/{order_id}`), so URLs with IDs don't explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
@@ -110,7 +110,7 @@ What it costs: with default settings, about 43 µs of CPU per request on an Appl
 
 ## Why you can trust it
 
-- Tested in CI on Python 3.11 to 3.15, fully typed, and used in production by its maintainer.
+- Tested in CI on Python 3.11 to 3.15, type-checked with `mypy --strict`, tested nightly against the newest OpenTelemetry releases, and used in production by its maintainer.
 - Releases are published with PyPI Trusted Publishing and signed attestations. CI runs `pip-audit` and generates an SBOM.
 - Security fixes are called out in the [changelog](https://github.com/Vitaee/FastapiObserver/blob/main/CHANGELOG.md). To report a vulnerability, see [SECURITY.md](https://github.com/Vitaee/FastapiObserver/blob/main/SECURITY.md).
 - Benchmarks are reproducible from [`examples/benchmarks`](https://github.com/Vitaee/FastapiObserver/tree/main/examples/benchmarks).

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/pyproject.toml

@@ -115,7 +115,10 @@ src = ["src", "tests"]
 select = ["E", "F"]
 
 [tool.mypy]
+strict = true
 ignore_missing_imports = false
+# prometheus_client's multiprocess module has no annotations.
+untyped_calls_exclude = ["prometheus_client.multiprocess"]
 
 [[tool.mypy.overrides]]
 module = ["orjson", "orjson.*"]

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0/src/fastapi_observer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 1.6.0
+Version: 1.8.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -147,7 +147,7 @@ Explicit variables and Python arguments always win over profile defaults. Every
 ## What you get
 
 - **One JSON line per request** with method, path, status, duration and client IP, and your service's name, environment and version on every line, including your own `logging` calls.
-- **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, and returned in the response.
+- **Request IDs** taken from `X-Request-ID` when the caller is a trusted proxy, generated otherwise, returned in the response and passed on to the services you call, so one ID finds a request's logs in every service.
 - **Redaction on by default.** Passwords, tokens, API keys, `Authorization` and cookies are masked before anything is written. Presets cover stricter needs (`strict`, `pci`, `gdpr`).
 - **Prometheus metrics** labelled by route template (`/orders/{order_id}`), so URLs with IDs don't explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
@@ -186,7 +186,7 @@ What it costs: with default settings, about 43 µs of CPU per request on an Appl
 
 ## Why you can trust it
 
-- Tested in CI on Python 3.11 to 3.15, fully typed, and used in production by its maintainer.
+- Tested in CI on Python 3.11 to 3.15, type-checked with `mypy --strict`, tested nightly against the newest OpenTelemetry releases, and used in production by its maintainer.
 - Releases are published with PyPI Trusted Publishing and signed attestations. CI runs `pip-audit` and generates an SBOM.
 - Security fixes are called out in the [changelog](https://github.com/Vitaee/FastapiObserver/blob/main/CHANGELOG.md). To report a vulnerability, see [SECURITY.md](https://github.com/Vitaee/FastapiObserver/blob/main/SECURITY.md).
 - Benchmarks are reproducible from [`examples/benchmarks`](https://github.com/Vitaee/FastapiObserver/tree/main/examples/benchmarks).

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapi_observer.egg-info/SOURCES.txt

@@ -33,18 +33,7 @@ src/fastapiobserver/logging/queueing.py
 src/fastapiobserver/logging/setup.py
 src/fastapiobserver/logging/state.py
 src/fastapiobserver/metrics/__init__.py
-src/fastapiobserver/metrics/builder.py
-src/fastapiobserver/metrics/contracts.py
-src/fastapiobserver/metrics/endpoint.py
-src/fastapiobserver/metrics/noop.py
-src/fastapiobserver/metrics/pathing.py
-src/fastapiobserver/metrics/registry.py
-src/fastapiobserver/metrics/prometheus/__init__.py
-src/fastapiobserver/metrics/prometheus/backend.py
-src/fastapiobserver/metrics/prometheus/client.py
-src/fastapiobserver/metrics/prometheus/collector.py
-src/fastapiobserver/metrics/prometheus/exemplars.py
-src/fastapiobserver/metrics/prometheus/multiprocess.py
+src/fastapiobserver/metrics/prometheus.py
 src/fastapiobserver/middleware/__init__.py
 src/fastapiobserver/middleware/body_capture.py
 src/fastapiobserver/middleware/context.py
@@ -53,7 +42,6 @@ src/fastapiobserver/middleware/headers.py
 src/fastapiobserver/middleware/ip.py
 src/fastapiobserver/middleware/metrics.py
 src/fastapiobserver/middleware/request_logging.py
-src/fastapiobserver/middleware/span_errors.py
 src/fastapiobserver/otel/__init__.py
 src/fastapiobserver/otel/exclusions.py
 src/fastapiobserver/otel/lifecycle.py
@@ -62,7 +50,6 @@ src/fastapiobserver/otel/metrics.py
 src/fastapiobserver/otel/resource.py
 src/fastapiobserver/otel/settings.py
 src/fastapiobserver/otel/tracing.py
-src/fastapiobserver/otel/types.py
 src/fastapiobserver/security/__init__.py
 src/fastapiobserver/security/normalize.py
 src/fastapiobserver/security/policy.py

fastapi_observer-1.8.0/src/fastapiobserver/_version.py

@@ -0,0 +1 @@
+__version__ = "1.8.0"

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapiobserver/config.py

@@ -2,11 +2,12 @@ from __future__ import annotations
 
 import logging
 import re
-from typing import Literal
+from typing import Annotated, Literal
 
 from pydantic import Field, field_validator
+from pydantic_settings import NoDecode
 
-from .utils import InternalSettingsBase, normalize_path, parse_csv
+from .utils import InternalSettingsBase, normalize_path, parse_csv, parse_csv_tuple
 
 _HEADER_NAME_RE = re.compile(r"^[A-Za-z0-9-]+$")
 DEFAULT_METRICS_EXCLUDE_PATHS = (
@@ -69,7 +70,7 @@ class ObservabilitySettings(InternalSettingsBase):
     metrics_enabled: bool = Field(default=False, validation_alias="METRICS_ENABLED")
     metrics_backend: str = Field(default="prometheus", validation_alias="METRICS_BACKEND")
     metrics_path: str = Field(default="/metrics", validation_alias="METRICS_PATH")
-    metrics_exclude_paths: tuple[str, ...] = Field(
+    metrics_exclude_paths: Annotated[tuple[str, ...], NoDecode] = Field(
         default=DEFAULT_METRICS_EXCLUDE_PATHS,
         validation_alias="METRICS_EXCLUDE_PATHS",
     )
@@ -85,6 +86,11 @@ class ObservabilitySettings(InternalSettingsBase):
         default=None, validation_alias="OTEL_EXCLUDED_URLS"
     )
 
+    # --- extra sinks from installed packages ---
+    log_sinks: Annotated[tuple[str, ...], NoDecode] = Field(
+        default=(), validation_alias="OBS_LOG_SINKS"
+    )
+
     # --- logtail (Better Stack) ---
     logtail_enabled: bool = Field(default=False, validation_alias="LOGTAIL_ENABLED")
     logtail_source_token: str | None = Field(
@@ -178,6 +184,11 @@ class ObservabilitySettings(InternalSettingsBase):
             return parsed
         return DEFAULT_METRICS_EXCLUDE_PATHS
 
+    @field_validator("log_sinks", mode="before")
+    @classmethod
+    def _parse_log_sinks(cls, value: object) -> tuple[str, ...]:
+        return parse_csv_tuple(value, ())
+
     @field_validator("metrics_exclude_paths")
     @classmethod
     def _normalize_metrics_exclude_paths(

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapiobserver/control_plane.py

@@ -6,11 +6,12 @@ import secrets
 import weakref
 from typing import Annotated, Literal
 
-from fastapi import APIRouter, Depends, FastAPI, Header, HTTPException, status
+from fastapi import APIRouter, Depends, FastAPI, Header, HTTPException, Request, status
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from .otel import get_trace_sampling_ratio, set_trace_sampling_ratio
+from .security import TrustedProxyPolicy, is_trusted_client_ip, resolve_client_ip
 from .utils import EnvLoadable, normalize_path
 
 __all__ = [
@@ -52,7 +53,15 @@ class ControlPlanePayload(BaseModel):
     trace_sampling_ratio: float | None = Field(default=None, ge=0.0, le=1.0)
 
 
-def mount_control_plane(app: FastAPI, settings: RuntimeControlSettings) -> None:
+def mount_control_plane(
+    app: FastAPI,
+    settings: RuntimeControlSettings,
+    trusted_proxy_policy: TrustedProxyPolicy | None = None,
+) -> None:
+    """Mount the runtime control endpoint.
+
+    Callers must come from ``OBS_TRUSTED_CIDRS`` and send the bearer token.
+    """
     if not settings.enabled:
         return
     if settings.auth_mode != "token":
@@ -69,9 +78,15 @@ def mount_control_plane(app: FastAPI, settings: RuntimeControlSettings) -> None:
     if normalized_path in mounted_paths:
         return
 
+    policy = trusted_proxy_policy or TrustedProxyPolicy.from_env()
+
     def authorize(
+        request: Request,
         authorization: Annotated[str | None, Header()] = None,
     ) -> None:
+        # Checked before the token, so callers outside the network can't guess it.
+        if not _is_trusted_caller(request, policy):
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Forbidden")
         current_token = os.getenv(settings.token_env_var)
         if not current_token:
             raise HTTPException(
@@ -107,6 +122,19 @@ def mount_control_plane(app: FastAPI, settings: RuntimeControlSettings) -> None:
     mounted_paths.add(normalized_path)
 
 
+def _is_trusted_caller(request: Request, policy: TrustedProxyPolicy) -> bool:
+    headers = request.scope["headers"]
+    if (
+        policy.enabled
+        and not policy.honor_forwarded_headers
+        and any(name.lower() == b"x-forwarded-for" for name, _ in headers)
+    ):
+        # Came through a proxy, so the peer address isn't the real caller's.
+        return False
+    peer = request.client.host if request.client else None
+    return is_trusted_client_ip(resolve_client_ip(peer, headers, policy), policy)
+
+
 def _current_runtime_settings() -> dict[str, object]:
     return {
         "log_level": logging.getLevelName(logging.getLogger().getEffectiveLevel()),

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapiobserver/db_tracing.py

@@ -12,7 +12,7 @@ Usage::
 
     engine = create_engine("postgresql://...")
     instrument_sqlalchemy(engine)
-    # SELECT * FROM users /*traceparent='00-abc123...',route='/api/users'*/
+    # SELECT * FROM users /*db_driver='psycopg2',traceparent='00-abc123...'*/
 
 Or for async engines::
 
@@ -35,9 +35,12 @@ _DEFAULT_COMMENTER_OPTIONS: dict[str, bool] = {
     "opentelemetry_values": True,  # injects traceparent
     "db_driver": True,
     "db_framework": False,  # noisy — omit by default
-    "route": True,
 }
 
+# OpenTelemetry's instrumentor is a singleton that ignores a second
+# ``instrument()`` call, so every call re-instruments all engines seen so far.
+_ENGINES: list[Any] = []
+
 _PACKAGE_HINT = "fastapi-observer[otel-sqlalchemy]"
 
 
@@ -58,38 +61,46 @@ def instrument_sqlalchemy(
         context to every query.
     commenter_options:
         Key-value pairs controlling which fields appear in the SQL
-        comment.  Defaults to ``traceparent``, ``db_driver``, and
-        ``route``.
+        comment (``opentelemetry_values``, ``db_driver``, ``db_framework``).
+        Defaults to the trace context and ``db_driver``.
+
+    Call it once per engine. The commenter settings of the latest call apply
+    to every instrumented engine.
     """
     try:
         instrumentor_module = lazy_import(
             "opentelemetry.instrumentation.sqlalchemy",
             package_hint=_PACKAGE_HINT,
         )
-        instrumentor = instrumentor_module.SQLAlchemyInstrumentor()
-
-        options = commenter_options or _DEFAULT_COMMENTER_OPTIONS
-
-        instrumentor.instrument(
-            engine=engine,
-            enable_commenter=enable_commenter,
-            commenter_options=options,
-        )
-        _LOGGER.info(
-            "db_tracing.instrumented",
-            extra={
-                "event": {
-                    "engine_url": str(engine.url),
-                    "commenter_enabled": enable_commenter,
-                },
-                "_skip_enrichers": True,
-            },
-        )
     except RuntimeError as exc:
         raise RuntimeError(
             "SQLAlchemy instrumentation requires "
             f"`pip install {_PACKAGE_HINT}`"
         ) from exc
+    instrumentor = instrumentor_module.SQLAlchemyInstrumentor()
+
+    if not any(known is engine for known in _ENGINES):
+        _ENGINES.append(engine)
+    if instrumentor.is_instrumented_by_opentelemetry:
+        instrumentor.uninstrument()
+    instrumentor.instrument(
+        engines=list(_ENGINES),
+        enable_commenter=enable_commenter,
+        commenter_options=commenter_options or _DEFAULT_COMMENTER_OPTIONS,
+    )
+
+    event = {"engine_url": str(engine.url), "commenter_enabled": enable_commenter}
+    if not instrumentor.is_instrumented_by_opentelemetry:
+        # OpenTelemetry refuses unsupported SQLAlchemy versions and only logs it.
+        _LOGGER.warning(
+            "db_tracing.not_instrumented",
+            extra={"event": event, "_skip_enrichers": True},
+        )
+        return
+    _LOGGER.info(
+        "db_tracing.instrumented",
+        extra={"event": event, "_skip_enrichers": True},
+    )
 
 
 def instrument_sqlalchemy_async(
@@ -134,6 +145,7 @@ def uninstrument_sqlalchemy() -> None:
         instrumentor_module.SQLAlchemyInstrumentor().uninstrument()
     except (ModuleNotFoundError, RuntimeError):
         pass
+    _ENGINES.clear()
 
 
 __all__ = [

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapiobserver/fastapi.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import logging
+import os
 import re
 import weakref
 import typing
+from urllib.parse import urlsplit, urlunsplit
 from collections.abc import Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
-from typing import Any, Literal
+from typing import Any, Literal, cast
 
 from fastapi import FastAPI
 
@@ -31,6 +33,7 @@ from .otel import (
     install_otel_logs,
     install_otel_metrics,
 )
+from .propagation import install_request_id_propagation
 from .security import SecurityPolicy, TrustedProxyPolicy
 
 _LOGGER = logging.getLogger("fastapiobserver.fastapi")
@@ -125,6 +128,7 @@ def install_observability(
         trusted_proxy_policy,
         metrics_backend,
     )
+    install_request_id_propagation(settings.request_id_header)
 
     # --- 7. Uvicorn access log ---
     # The middleware's `request.completed` line carries the same fields, so drop
@@ -135,7 +139,55 @@ def install_observability(
 
     # --- 8. Runtime control plane ---
     if runtime_control_settings and runtime_control_settings.enabled:
-        mount_control_plane(app, runtime_control_settings)
+        mount_control_plane(app, runtime_control_settings, trusted_proxy_policy)
+
+    # --- 9. One line with the settings that took effect ---
+    _LOGGER.info(
+        "observability.configured",
+        extra={
+            "event": {
+                "profile": os.getenv("OBS_PROFILE", "").strip().lower() or None,
+                "log_level": settings.log_level,
+                "metrics_path": (
+                    settings.metrics_path
+                    if (settings.metrics_enabled if metrics_enabled is None else metrics_enabled)
+                    else None
+                ),
+                "tracing": otel_settings.enabled,
+                "otlp_endpoint": _endpoint_for_log(otel_settings.otlp_endpoint),
+                "otlp_protocol": otel_settings.protocol,
+                "trace_sampling_ratio": otel_settings.trace_sampling_ratio,
+                "otel_logs_mode": (
+                    otel_logs_settings.logs_mode if otel_logs_settings.enabled else None
+                ),
+                "otel_metrics": otel_metrics_settings.enabled,
+                "redaction_mode": security_policy.redaction_mode,
+                "body_capture": (
+                    security_policy.log_request_body or security_policy.log_response_body
+                ),
+                "trusted_cidrs": (
+                    list(trusted_proxy_policy.trusted_cidrs)
+                    if trusted_proxy_policy.enabled
+                    else None
+                ),
+                "honor_forwarded_headers": trusted_proxy_policy.honor_forwarded_headers,
+                "request_id_header": settings.request_id_header,
+                "control_plane": (
+                    runtime_control_settings.path if runtime_control_settings.enabled else None
+                ),
+                "log_sinks": list(settings.log_sinks),
+            },
+            "_skip_enrichers": True,
+        },
+    )
+
+
+def _endpoint_for_log(endpoint: str | None) -> str | None:
+    """*endpoint* without credentials, query or fragment, which can carry tokens."""
+    if not endpoint:
+        return None
+    parts = urlsplit(endpoint)
+    return urlunsplit((parts.scheme, parts.netloc.rpartition("@")[2], parts.path, "", ""))
 
 
 def _setup_structured_logging(
@@ -146,6 +198,9 @@ def _setup_structured_logging(
     security_policy: SecurityPolicy,
     audit_key_provider: object | None,
 ) -> None:
+    # Hook the lifespan before install_otel_logs does, so on shutdown the log
+    # queue drains into the OTLP handler before its provider is shut down.
+    _register_logging_shutdown_hook(app)
     otel_log_handler = None
     logs_mode: Literal["local_json", "otlp", "both"] = "local_json"
     if otel_logs_settings and otel_logs_settings.enabled:
@@ -172,7 +227,6 @@ def _setup_structured_logging(
         extra_handlers=extra_handlers,
         audit_key_provider=audit_key_provider,
     )
-    _register_logging_shutdown_hook(app)
 
 
 def _setup_metrics_backend(
@@ -260,7 +314,8 @@ def _setup_request_middleware(
         )
 
     for middleware in app.user_middleware:
-        if middleware.cls is RequestLoggingMiddleware:
+        # Starlette types `cls` as a middleware factory protocol, which mypy can't compare.
+        if cast(object, middleware.cls) is RequestLoggingMiddleware:
             return
 
     app.add_middleware(

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapiobserver/integrations/strawberry.py

@@ -60,7 +60,7 @@ class StrawberryObservabilityExtension:
 
         # 2. Update OpenTelemetry Trace if active
         try:
-            from opentelemetry import trace as otel_trace  # type: ignore
+            from opentelemetry import trace as otel_trace
 
             span = otel_trace.get_current_span()
             if span and span.is_recording():

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapiobserver/logging/circuit_breaker.py

@@ -69,10 +69,22 @@ class SinkCircuitBreakerHandler(logging.Handler):
         self._half_open_total = 0
         self._closes_total = 0
 
+        # Stdlib handlers catch their own write errors and only report them
+        # through handleError(), so count those reports as failures too.
+        self._delegate_failed = False
+        report_error = delegate.handleError
+
+        def _count_and_report(record: logging.LogRecord) -> None:
+            self._delegate_failed = True
+            report_error(record)
+
+        delegate.handleError = _count_and_report  # type: ignore[method-assign]
+
     def emit(self, record: logging.LogRecord) -> None:
         if self._should_skip():
             return
 
+        self._delegate_failed = False
         try:
             self._delegate.handle(record)
         except Exception:
@@ -80,7 +92,10 @@ class SinkCircuitBreakerHandler(logging.Handler):
             self.handleError(record)
             return
 
-        self._record_success()
+        if self._delegate_failed:
+            self._record_failure()
+        else:
+            self._record_success()
 
     def setFormatter(self, fmt: logging.Formatter | None) -> None:  # noqa: N802
         super().setFormatter(fmt)

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapiobserver/logging/filters.py

@@ -48,9 +48,9 @@ class TraceContextFilter(logging.Filter):
                 )
 
         if trace_id:
-            record.trace_id = trace_id  # type: ignore[attr-defined]
+            record.trace_id = trace_id
         if span_id:
-            record.span_id = span_id  # type: ignore[attr-defined]
+            record.span_id = span_id
         return True
 
 

{fastapi_observer-1.6.0 → fastapi_observer-1.8.0}/src/fastapiobserver/logging/formatter.py

@@ -122,7 +122,7 @@ def _as_dict(value: Mapping[str, Any]) -> dict[str, Any]:
 
 def _json_dumps(payload: dict[str, Any]) -> str:
     if orjson is not None:
-        return orjson.dumps(payload).decode("utf-8")
+        return str(orjson.dumps(payload), "utf-8")
     return json.dumps(payload, ensure_ascii=True, default=str)
 
 

fastapi_observer-1.8.0/src/fastapiobserver/metrics/__init__.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import re
+from typing import Callable, Protocol
+
+from fastapi import FastAPI
+
+from ..config import MetricsFormat
+from .prometheus import (
+    PrometheusMetricsBackend,
+    _build_prometheus_metrics_backend,
+    mark_prometheus_process_dead,
+    mount_metrics_endpoint,
+)
+
+
+class MetricsBackend(Protocol):
+    """Interface for metrics recording backends."""
+
+    def observe(
+        self,
+        method: str,
+        path: str,
+        status_code: int,
+        duration_seconds: float,
+    ) -> None: ...
+
+
+class MountableMetricsBackend(Protocol):
+    """Optional extension for backends that can mount their endpoint."""
+
+    def mount_endpoint(
+        self,
+        app: FastAPI,
+        *,
+        path: str = "/metrics",
+        metrics_format: MetricsFormat = "negotiate",
+    ) -> None: ...
+
+
+MetricsBackendFactory = Callable[..., MetricsBackend]
+
+
+class NoopMetricsBackend:
+    """No-op backend that silently discards all observations."""
+
+    def observe(
+        self,
+        method: str,
+        path: str,
+        status_code: int,
+        duration_seconds: float,
+    ) -> None:
+        return None
+
+
+_UUID_RE = re.compile(
+    r"/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}"
+)
+_NUMBER_RE = re.compile(r"/\d+")
+_HEX_RE = re.compile(r"/[0-9a-fA-F]{16,}")
+
+
+def collapse_dynamic_segments(path: str) -> str:
+    """Replace dynamic path segments with ``/:id`` to control label cardinality."""
+    normalized = _UUID_RE.sub("/:id", path)
+    normalized = _HEX_RE.sub("/:id", normalized)
+    return _NUMBER_RE.sub("/:id", normalized)
+
+
+_BACKEND_FACTORIES: dict[str, MetricsBackendFactory] = {}
+
+
+def register_metrics_backend(name: str, factory: MetricsBackendFactory) -> None:
+    normalized_name = name.strip().lower()
+    if not normalized_name:
+        raise ValueError("Metrics backend name cannot be empty")
+    _BACKEND_FACTORIES[normalized_name] = factory
+
+
+def unregister_metrics_backend(name: str) -> None:
+    _BACKEND_FACTORIES.pop(name.strip().lower(), None)
+
+
+def get_registered_metrics_backends() -> dict[str, MetricsBackendFactory]:
+    return dict(_BACKEND_FACTORIES)
+
+
+def build_metrics_backend(
+    enabled: bool,
+    *,
+    service: str = "api",
+    environment: str = "development",
+    exemplars_enabled: bool = False,
+    backend: str = "prometheus",
+) -> MetricsBackend:
+    """Factory for selecting the appropriate metrics backend."""
+    if not enabled:
+        return NoopMetricsBackend()
+    factory = _BACKEND_FACTORIES.get(backend.strip().lower())
+    if factory is None:
+        available_csv = ", ".join(sorted(_BACKEND_FACTORIES)) or "(none)"
+        raise ValueError(
+            f"Unknown metrics backend: {backend!r}. Available backends: {available_csv}"
+        )
+    return factory(
+        service=service,
+        environment=environment,
+        exemplars_enabled=exemplars_enabled,
+    )
+
+
+def mount_backend_metrics_endpoint(
+    app: FastAPI,
+    backend: MetricsBackend,
+    *,
+    path: str = "/metrics",
+    metrics_format: MetricsFormat = "negotiate",
+) -> bool:
+    mount_endpoint = getattr(backend, "mount_endpoint", None)
+    if not callable(mount_endpoint):
+        return False
+    mount_endpoint(app, path=path, metrics_format=metrics_format)
+    return True
+
+
+register_metrics_backend("prometheus", _build_prometheus_metrics_backend)
+
+__all__ = [
+    "MetricsBackend",
+    "MountableMetricsBackend",
+    "MetricsBackendFactory",
+    "MetricsFormat",
+    "NoopMetricsBackend",
+    "collapse_dynamic_segments",
+    "register_metrics_backend",
+    "unregister_metrics_backend",
+    "get_registered_metrics_backends",
+    "build_metrics_backend",
+    "mount_backend_metrics_endpoint",
+    "PrometheusMetricsBackend",
+    "mark_prometheus_process_dead",
+    "mount_metrics_endpoint",
+]