fastapi-observer 1.7.0__tar.gz → 1.9.0__tar.gz

{fastapi_observer-1.7.0/src/fastapi_observer.egg-info → fastapi_observer-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 1.7.0
+Version: 1.9.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -147,9 +147,9 @@ 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.
+- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), and 404s for paths no route matches share one `<unmatched>` label, so neither IDs nor scanners explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
 - **Non-blocking log writes.** Lines are written from a background thread, so a slow stdout never stalls the event loop.
 
@@ -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.7.0 → fastapi_observer-1.9.0}/README.md

@@ -71,9 +71,9 @@ 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.
+- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), and 404s for paths no route matches share one `<unmatched>` label, so neither IDs nor scanners explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
 - **Non-blocking log writes.** Lines are written from a background thread, so a slow stdout never stalls the event loop.
 
@@ -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.7.0 → fastapi_observer-1.9.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.7.0 → fastapi_observer-1.9.0/src/fastapi_observer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 1.7.0
+Version: 1.9.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -147,9 +147,9 @@ 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.
+- **Prometheus metrics** labelled by route template (`/orders/{order_id}`), and 404s for paths no route matches share one `<unmatched>` label, so neither IDs nor scanners explode cardinality.
 - **OpenTelemetry traces** with `trace_id` and `span_id` in every log line, and optional log export over OTLP.
 - **Non-blocking log writes.** Lines are written from a background thread, so a slow stdout never stalls the event loop.
 
@@ -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.9.0/src/fastapiobserver/_version.py

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

{fastapi_observer-1.7.0 → fastapi_observer-1.9.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.7.0 → fastapi_observer-1.9.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.7.0 → fastapi_observer-1.9.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(
@@ -262,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.7.0 → fastapi_observer-1.9.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.7.0 → fastapi_observer-1.9.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.7.0 → fastapi_observer-1.9.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.7.0 → fastapi_observer-1.9.0}/src/fastapiobserver/middleware/events.py

@@ -68,23 +68,28 @@ def _classify_error(status_code: int, error: Exception | None) -> str:
     return "ok"
 
 
-def _extract_route_template(scope: Scope, raw_path: str) -> str:
-    """Return the matched route template for bounded metric cardinality.
+UNMATCHED_ROUTE = "<unmatched>"
 
-    After Starlette's router runs, ``scope["route"]`` contains the matched
-    ``Route`` object whose ``.path`` is the template string
-    (e.g. ``/users/{user_id}``).
 
-    Falls back to *raw_path* when:
-    * No route matched (404 / unmatched sub-apps)
-    * ``scope["route"]`` is not a Starlette ``Route`` with a ``path`` attr
+def _extract_route_template(scope: Scope, raw_path: str, status_code: int) -> str:
+    """Return the metrics ``path`` label: the matched route template if known.
+
+    After routing, ``scope["route"]`` holds the matched route, whose ``.path``
+    is the template (e.g. ``/users/{user_id}``). Without one, a 404 means no
+    route matched, mostly scanners, so those share ``UNMATCHED_ROUTE`` instead
+    of adding a time series per URL. Other requests without a template keep
+    *raw_path*: FastAPI doesn't record plain Starlette routes, such as ones
+    added with ``app.add_route()``, in the scope.
     """
-    route = scope.get("route")
-    if route is not None:
-        template = getattr(route, "path", None)
-        if template:
-            return template
-    return raw_path
+    template = getattr(scope.get("route"), "path", None)
+    if isinstance(template, str) and template:
+        return template
+    return UNMATCHED_ROUTE if status_code == 404 else raw_path
 
-__all__ = ["_RequestEventBuilder", "_classify_error", "_extract_route_template", 
-           "_sanitize_exception_message"]
+__all__ = [
+    "UNMATCHED_ROUTE",
+    "_RequestEventBuilder",
+    "_classify_error",
+    "_extract_route_template",
+    "_sanitize_exception_message",
+]

{fastapi_observer-1.7.0 → fastapi_observer-1.9.0}/src/fastapiobserver/middleware/metrics.py

@@ -38,12 +38,16 @@ class _MetricsRecorder:
         if scope and "app" in scope:
             app = scope["app"]
             state = getattr(app.state, "_observability_state", None)
-            if state is not None:
+            # Filled when the app starts; without a lifespan, keep the settings' list.
+            if state is not None and state.excluded_urls:
                 excluded_urls = state.excluded_urls
 
+        # Also check the request's own path: unmatched requests share one label.
+        raw_path = scope.get("path") if scope else None
         if (
             path in excluded_urls
             or collapsed_path in excluded_urls
+            or raw_path in excluded_urls
         ):
             return
         try:

{fastapi_observer-1.7.0 → fastapi_observer-1.9.0}/src/fastapiobserver/middleware/request_logging.py

@@ -168,7 +168,7 @@ class RequestLoggingMiddleware:
             )
 
         # Prefer route template for bounded cardinality
-        route_template = _extract_route_template(scope, path)
+        route_template = _extract_route_template(scope, path, status_code)
 
         self.metrics_recorder.observe(
             method=method,

{fastapi_observer-1.7.0 → fastapi_observer-1.9.0}/src/fastapiobserver/otel/resource.py

@@ -93,7 +93,8 @@ def build_otlp_exporter(
 
 def import_otel_module(name: str) -> ModuleType:
     try:
-        return lazy_import(name, package_hint="fastapi-observer[otel]")
+        module: ModuleType = lazy_import(name, package_hint="fastapi-observer[otel]")
+        return module
     except RuntimeError as exc:
         raise RuntimeError(
             "OpenTelemetry support requires `pip install fastapi-observer[otel]`"

{fastapi_observer-1.7.0 → fastapi_observer-1.9.0}/src/fastapiobserver/propagation.py

@@ -16,17 +16,98 @@ Or for automatic instrumentation::
 
     from fastapiobserver.propagation import instrument_httpx_client
 
-    instrument_httpx_client()  # all httpx calls get traceparent automatically
+    instrument_httpx_client()  # all httpx calls get traceparent and the request ID
+
+``install_observability()`` sets the request ID header to forward from
+``REQUEST_ID_HEADER``.
 """
 
 from __future__ import annotations
 
+import importlib.util
 import logging
+from collections.abc import Mapping
 from typing import Any
 
+from .request_context import get_request_id
 from .utils import lazy_import
 
 _LOGGER = logging.getLogger("fastapiobserver.propagation")
+# ponytail: one header per process, the last install_observability() wins; key it
+# per app if one process ever runs apps with different REQUEST_ID_HEADER values.
+_request_id_header = "x-request-id"
+
+
+# ---------------------------------------------------------------------------
+# Request ID forwarding
+# ---------------------------------------------------------------------------
+
+
+def _request_id_to_forward(carrier: Any) -> str | None:
+    """The current request ID, unless *carrier* already has a request ID header."""
+    request_id = get_request_id()
+    if request_id is None:
+        return None
+    if isinstance(carrier, Mapping) and any(
+        str(key).lower() == _request_id_header for key in carrier
+    ):
+        return None
+    return request_id
+
+
+def install_request_id_propagation(header: str) -> None:
+    """Send the current request ID as *header* on outbound calls.
+
+    Adds a propagator next to OpenTelemetry's global one, so every client
+    OpenTelemetry instruments (httpx, requests, ...) forwards the request ID
+    alongside ``traceparent``. Without OpenTelemetry installed, only
+    ``inject_trace_headers()`` forwards it.
+    """
+    global _request_id_header
+    _request_id_header = header
+    try:
+        from opentelemetry import propagate
+        from opentelemetry.context import Context
+        from opentelemetry.propagators.composite import CompositePropagator
+        from opentelemetry.propagators.textmap import (
+            Getter,
+            Setter,
+            TextMapPropagator,
+            default_getter,
+            default_setter,
+        )
+    except ImportError:
+        return
+
+    current = propagate.get_global_textmap()
+    if header in current.fields:
+        return
+
+    class RequestIdPropagator(TextMapPropagator):
+        def inject(
+            self,
+            carrier: Any,
+            context: Context | None = None,
+            setter: Setter[Any] = default_setter,
+        ) -> None:
+            request_id = _request_id_to_forward(carrier)
+            if request_id is not None:
+                setter.set(carrier, _request_id_header, request_id)
+
+        def extract(
+            self,
+            carrier: Any,
+            context: Context | None = None,
+            getter: Getter[Any] = default_getter,
+        ) -> Context:
+            # The middleware reads incoming request IDs, and only from trusted proxies.
+            return context if context is not None else Context()
+
+        @property
+        def fields(self) -> set[str]:
+            return {_request_id_header}
+
+    propagate.set_global_textmap(CompositePropagator([current, RequestIdPropagator()]))
 
 
 # ---------------------------------------------------------------------------
@@ -35,11 +116,12 @@ _LOGGER = logging.getLogger("fastapiobserver.propagation")
 
 
 def inject_trace_headers(headers: dict[str, str] | None = None) -> dict[str, str]:
-    """Inject the current OTel trace context into *headers*.
+    """Inject the current request ID and OTel trace context into *headers*.
 
-    Returns the (mutated) *headers* dict with ``traceparent`` and
-    ``tracestate`` entries added when a valid span exists.  If OTel is
-    not installed, *headers* is returned unchanged.
+    Returns the (mutated) *headers* dict with the request ID header, and
+    ``traceparent`` and ``tracestate`` entries when a valid span exists.
+    A request ID already in *headers* is kept. If OTel is not installed,
+    only the request ID is added.
 
     Parameters
     ----------
@@ -48,6 +130,9 @@ def inject_trace_headers(headers: dict[str, str] | None = None) -> dict[str, str
     """
     if headers is None:
         headers = {}
+    request_id = _request_id_to_forward(headers)
+    if request_id is not None:
+        headers[_request_id_header] = request_id
     try:
         from opentelemetry.propagate import inject
 
@@ -78,8 +163,17 @@ def instrument_httpx_client(client: Any | None = None) -> None:
     instrumented.  When ``None``, **all** ``httpx`` clients are
     instrumented globally.
 
-    Requires ``pip install fastapi-observer[otel-httpx]``.
+    Requires ``pip install fastapi-observer[otel-httpx]`` and the ``httpx``
+    package. Other clients, ``httpx2`` included, need a request hook instead;
+    see the OpenTelemetry guide.
     """
+    # OpenTelemetry's instrumentor only logs an error and does nothing without httpx.
+    if importlib.util.find_spec("httpx") is None:
+        raise RuntimeError(
+            "instrument_httpx_client() needs the `httpx` package, which is not installed. "
+            "For other clients, such as httpx2, call "
+            "`opentelemetry.propagate.inject(request.headers)` from a request hook."
+        )
     try:
         instrumentor_module = lazy_import(
             "opentelemetry.instrumentation.httpx",

fastapi_observer-1.9.0/src/fastapiobserver/sinks/discovery.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+import threading
+from collections.abc import Collection
+
+from .protocol import LogSink
+from .registry import register_sink
+
+_LOGGER = logging.getLogger("fastapiobserver.sinks")
+_LOADED: set[str] = set()
+_LOADED_LOCK = threading.Lock()
+
+
+def _forget_loaded() -> None:
+    with _LOADED_LOCK:
+        _LOADED.clear()
+
+
+def discover_entry_point_sinks(enabled: Collection[str] = ()) -> None:
+    """Register the ``fastapiobserver.log_sinks`` entry points named in *enabled*.
+
+    Other entry points are never imported, so an installed package can't
+    receive your logs unless you list it in ``OBS_LOG_SINKS``.
+    """
+    with _LOADED_LOCK:
+        try:
+            group = importlib.metadata.entry_points(group="fastapiobserver.log_sinks")
+        except Exception:
+            _LOGGER.debug(
+                "sinks.entry_point.discover_failed",
+                exc_info=True,
+                extra={"_skip_enrichers": True},
+            )
+            return
+
+        names = {ep.name for ep in group}
+        for message, skipped in (
+            ("sinks.entry_point.not_enabled", names - set(enabled)),
+            ("sinks.entry_point.missing", set(enabled) - names),
+        ):
+            if skipped:
+                _LOGGER.warning(
+                    message,
+                    extra={
+                        "event": {"entry_points": sorted(skipped), "setting": "OBS_LOG_SINKS"},
+                        "_skip_enrichers": True,
+                    },
+                )
+
+        for ep in group:
+            if ep.name not in enabled or ep.name in _LOADED:
+                continue
+            try:
+                sink = ep.load()()
+                if isinstance(sink, LogSink):
+                    register_sink(sink)
+                    _LOADED.add(ep.name)
+                    _LOGGER.debug(
+                        "sinks.entry_point.loaded",
+                        extra={
+                            "event": {"sink_name": sink.name, "entry_point": ep.name},
+                            "_skip_enrichers": True,
+                        },
+                    )
+            except Exception:
+                _LOGGER.warning(
+                    "sinks.entry_point.failed",
+                    exc_info=True,
+                    extra={
+                        "event": {"entry_point": ep.name},
+                        "_skip_enrichers": True,
+                    },
+                )
+
+__all__ = ["discover_entry_point_sinks"]