fastapi-observer 0.3.1__tar.gz → 0.3.2__tar.gz

{fastapi_observer-0.3.1/src/fastapi_observer.egg-info → fastapi_observer-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.3.1
+Version: 0.3.2
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -65,6 +65,7 @@ Requires-Dist: pytest>=9.0.2; extra == "dev"
 Requires-Dist: pytest-randomly>=3.16.0; extra == "dev"
 Requires-Dist: ruff>=0.15.1; extra == "dev"
 Requires-Dist: cyclonedx-bom>=7.2.1; extra == "dev"
+Requires-Dist: uvicorn>=0.30.0; extra == "dev"
 Dynamic: license-file
 
 # fastapi-observer
@@ -570,11 +571,57 @@ kubectl -n observability rollout status deployment/traffic-generator
 kubectl -n observability port-forward svc/grafana 3000:3000
 ```
 
-Open [http://localhost:3000](http://localhost:3000).  
+Open [http://localhost:3000](http://localhost:3000).
 Full guide: [`kubernetes.md`](kubernetes.md)
 
 ---
 
+## Low-Overhead & Production Tuning (Advanced)
+
+`fastapi-observer` integrates natively with the core OpenTelemetry Python SDK, meaning you can aggressively tune its resource usage purely via standard environment variables without altering your application code.
+
+For high-throughput services (e.g. `10k+ RPS`), apply these exact variables to minimize the observer footprint:
+
+### 1. Head-Based Sampling
+
+Tracing 100% of requests is too expensive at scale. You should configure `fastapi-observer` to respect upstream trace flags, while only sampling a fraction of net-new requests:
+
+```bash
+# Keep the parent's sample decision if it exists, otherwise sample 5%
+export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
+export OTEL_TRACES_SAMPLER_ARG="0.05"
+```
+
+### 2. Exclude Noisy URLs from the SDK
+
+Do not waste cycles generating spans for health checks or static assets. `fastapi-observer` will auto-derive metrics exclusions, but you can explicitly drop them from tracing at the C-extension level:
+
+```bash
+export OTEL_PYTHON_FASTAPI_EXCLUDED_URLS="healthz,metrics,favicon.ico"
+```
+
+### 3. Cap Span Attributes
+
+Prevent large, unmanageable spans from consuming excessive memory in the `BatchSpanProcessor`:
+
+```bash
+export OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT="128"
+export OTEL_SPAN_EVENT_COUNT_LIMIT="128"
+export OTEL_SPAN_LINK_COUNT_LIMIT="128"
+```
+
+### 4. Optimize Output Buffers
+
+The default OpenTelemetry batch limits are too conservative for high-throughput ASGI microservices. Increase the max queue limits so spikes aren't dropped, but decrease the timeout so the process memory is flushed faster:
+
+```bash
+export OTEL_BSP_MAX_QUEUE_SIZE="10000"
+export OTEL_BSP_MAX_EXPORT_BATCH_SIZE="5000"
+export OTEL_BSP_SCHEDULE_DELAY="1000"
+```
+
+---
+
 ## Examples
 
 The `examples/` directory contains runnable demos:
@@ -729,7 +776,36 @@ install_observability(app, settings, security_policy=SecurityPolicy(log_request_
 app.add_middleware(CORSMiddleware, allow_origins=["*"])
 ```
 
-### Multi-worker Gunicorn with Prometheus
+### Multi-worker Gunicorn
+
+> [!WARNING]
+> `--preload-app` is dangerous if visibility is initialized at the module level.
+>
+> When `--preload-app` is used, the application is loaded into the master process *before* forking the worker processes. `fastapi-observer` uses a highly-performant background thread (`QueueListener`) for non-blocking logging, and OpenTelemetry similarly spawns background export threads.
+>
+> Threads **do not survive** a process fork. If you call `install_observability()` at the module level (e.g., right under `app = FastAPI()`), the background threads will be created in the master process, and all workers will silently drop logs because their logging threads never started.
+>
+> **How to fix:** Either remove `--preload-app`, OR initialize observability inside the FastAPI `lifespan` context manager so it starts safely after the fork inside each worker:
+>
+> ```python
+> from contextlib import asynccontextmanager
+> from fastapi import FastAPI
+> from fastapiobserver import ObservabilitySettings, install_observability
+>
+> settings = ObservabilitySettings(service="api")
+>
+> @asynccontextmanager
+> async def lifespan(app: FastAPI):
+>     install_observability(app, settings) # Safely initializes per-worker
+>     yield
+>     # fastapiobserver automatically registers shutdown hooks so no teardown needed here
+>
+> app = FastAPI(lifespan=lifespan)
+> ```
+
+#### Prometheus Multiprocess Mode
+
+If you are using Prometheus with multiple Gunicorn workers, you must configure a shared metrics directory:
 
 ```bash
 export PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus-metrics

{fastapi_observer-0.3.1 → fastapi_observer-0.3.2}/README.md

@@ -501,11 +501,57 @@ kubectl -n observability rollout status deployment/traffic-generator
 kubectl -n observability port-forward svc/grafana 3000:3000
 ```
 
-Open [http://localhost:3000](http://localhost:3000).  
+Open [http://localhost:3000](http://localhost:3000).
 Full guide: [`kubernetes.md`](kubernetes.md)
 
 ---
 
+## Low-Overhead & Production Tuning (Advanced)
+
+`fastapi-observer` integrates natively with the core OpenTelemetry Python SDK, meaning you can aggressively tune its resource usage purely via standard environment variables without altering your application code.
+
+For high-throughput services (e.g. `10k+ RPS`), apply these exact variables to minimize the observer footprint:
+
+### 1. Head-Based Sampling
+
+Tracing 100% of requests is too expensive at scale. You should configure `fastapi-observer` to respect upstream trace flags, while only sampling a fraction of net-new requests:
+
+```bash
+# Keep the parent's sample decision if it exists, otherwise sample 5%
+export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
+export OTEL_TRACES_SAMPLER_ARG="0.05"
+```
+
+### 2. Exclude Noisy URLs from the SDK
+
+Do not waste cycles generating spans for health checks or static assets. `fastapi-observer` will auto-derive metrics exclusions, but you can explicitly drop them from tracing at the C-extension level:
+
+```bash
+export OTEL_PYTHON_FASTAPI_EXCLUDED_URLS="healthz,metrics,favicon.ico"
+```
+
+### 3. Cap Span Attributes
+
+Prevent large, unmanageable spans from consuming excessive memory in the `BatchSpanProcessor`:
+
+```bash
+export OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT="128"
+export OTEL_SPAN_EVENT_COUNT_LIMIT="128"
+export OTEL_SPAN_LINK_COUNT_LIMIT="128"
+```
+
+### 4. Optimize Output Buffers
+
+The default OpenTelemetry batch limits are too conservative for high-throughput ASGI microservices. Increase the max queue limits so spikes aren't dropped, but decrease the timeout so the process memory is flushed faster:
+
+```bash
+export OTEL_BSP_MAX_QUEUE_SIZE="10000"
+export OTEL_BSP_MAX_EXPORT_BATCH_SIZE="5000"
+export OTEL_BSP_SCHEDULE_DELAY="1000"
+```
+
+---
+
 ## Examples
 
 The `examples/` directory contains runnable demos:
@@ -660,7 +706,36 @@ install_observability(app, settings, security_policy=SecurityPolicy(log_request_
 app.add_middleware(CORSMiddleware, allow_origins=["*"])
 ```
 
-### Multi-worker Gunicorn with Prometheus
+### Multi-worker Gunicorn
+
+> [!WARNING]
+> `--preload-app` is dangerous if visibility is initialized at the module level.
+>
+> When `--preload-app` is used, the application is loaded into the master process *before* forking the worker processes. `fastapi-observer` uses a highly-performant background thread (`QueueListener`) for non-blocking logging, and OpenTelemetry similarly spawns background export threads.
+>
+> Threads **do not survive** a process fork. If you call `install_observability()` at the module level (e.g., right under `app = FastAPI()`), the background threads will be created in the master process, and all workers will silently drop logs because their logging threads never started.
+>
+> **How to fix:** Either remove `--preload-app`, OR initialize observability inside the FastAPI `lifespan` context manager so it starts safely after the fork inside each worker:
+>
+> ```python
+> from contextlib import asynccontextmanager
+> from fastapi import FastAPI
+> from fastapiobserver import ObservabilitySettings, install_observability
+>
+> settings = ObservabilitySettings(service="api")
+>
+> @asynccontextmanager
+> async def lifespan(app: FastAPI):
+>     install_observability(app, settings) # Safely initializes per-worker
+>     yield
+>     # fastapiobserver automatically registers shutdown hooks so no teardown needed here
+>
+> app = FastAPI(lifespan=lifespan)
+> ```
+
+#### Prometheus Multiprocess Mode
+
+If you are using Prometheus with multiple Gunicorn workers, you must configure a shared metrics directory:
 
 ```bash
 export PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus-metrics

{fastapi_observer-0.3.1 → fastapi_observer-0.3.2}/pyproject.toml

@@ -86,6 +86,7 @@ dev = [
     "pytest-randomly>=3.16.0",
     "ruff>=0.15.1",
     "cyclonedx-bom>=7.2.1",
+    "uvicorn>=0.30.0",
 ]
 
 [tool.setuptools]

{fastapi_observer-0.3.1 → fastapi_observer-0.3.2/src/fastapi_observer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.3.1
+Version: 0.3.2
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -65,6 +65,7 @@ Requires-Dist: pytest>=9.0.2; extra == "dev"
 Requires-Dist: pytest-randomly>=3.16.0; extra == "dev"
 Requires-Dist: ruff>=0.15.1; extra == "dev"
 Requires-Dist: cyclonedx-bom>=7.2.1; extra == "dev"
+Requires-Dist: uvicorn>=0.30.0; extra == "dev"
 Dynamic: license-file
 
 # fastapi-observer
@@ -570,11 +571,57 @@ kubectl -n observability rollout status deployment/traffic-generator
 kubectl -n observability port-forward svc/grafana 3000:3000
 ```
 
-Open [http://localhost:3000](http://localhost:3000).  
+Open [http://localhost:3000](http://localhost:3000).
 Full guide: [`kubernetes.md`](kubernetes.md)
 
 ---
 
+## Low-Overhead & Production Tuning (Advanced)
+
+`fastapi-observer` integrates natively with the core OpenTelemetry Python SDK, meaning you can aggressively tune its resource usage purely via standard environment variables without altering your application code.
+
+For high-throughput services (e.g. `10k+ RPS`), apply these exact variables to minimize the observer footprint:
+
+### 1. Head-Based Sampling
+
+Tracing 100% of requests is too expensive at scale. You should configure `fastapi-observer` to respect upstream trace flags, while only sampling a fraction of net-new requests:
+
+```bash
+# Keep the parent's sample decision if it exists, otherwise sample 5%
+export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
+export OTEL_TRACES_SAMPLER_ARG="0.05"
+```
+
+### 2. Exclude Noisy URLs from the SDK
+
+Do not waste cycles generating spans for health checks or static assets. `fastapi-observer` will auto-derive metrics exclusions, but you can explicitly drop them from tracing at the C-extension level:
+
+```bash
+export OTEL_PYTHON_FASTAPI_EXCLUDED_URLS="healthz,metrics,favicon.ico"
+```
+
+### 3. Cap Span Attributes
+
+Prevent large, unmanageable spans from consuming excessive memory in the `BatchSpanProcessor`:
+
+```bash
+export OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT="128"
+export OTEL_SPAN_EVENT_COUNT_LIMIT="128"
+export OTEL_SPAN_LINK_COUNT_LIMIT="128"
+```
+
+### 4. Optimize Output Buffers
+
+The default OpenTelemetry batch limits are too conservative for high-throughput ASGI microservices. Increase the max queue limits so spikes aren't dropped, but decrease the timeout so the process memory is flushed faster:
+
+```bash
+export OTEL_BSP_MAX_QUEUE_SIZE="10000"
+export OTEL_BSP_MAX_EXPORT_BATCH_SIZE="5000"
+export OTEL_BSP_SCHEDULE_DELAY="1000"
+```
+
+---
+
 ## Examples
 
 The `examples/` directory contains runnable demos:
@@ -729,7 +776,36 @@ install_observability(app, settings, security_policy=SecurityPolicy(log_request_
 app.add_middleware(CORSMiddleware, allow_origins=["*"])
 ```
 
-### Multi-worker Gunicorn with Prometheus
+### Multi-worker Gunicorn
+
+> [!WARNING]
+> `--preload-app` is dangerous if visibility is initialized at the module level.
+>
+> When `--preload-app` is used, the application is loaded into the master process *before* forking the worker processes. `fastapi-observer` uses a highly-performant background thread (`QueueListener`) for non-blocking logging, and OpenTelemetry similarly spawns background export threads.
+>
+> Threads **do not survive** a process fork. If you call `install_observability()` at the module level (e.g., right under `app = FastAPI()`), the background threads will be created in the master process, and all workers will silently drop logs because their logging threads never started.
+>
+> **How to fix:** Either remove `--preload-app`, OR initialize observability inside the FastAPI `lifespan` context manager so it starts safely after the fork inside each worker:
+>
+> ```python
+> from contextlib import asynccontextmanager
+> from fastapi import FastAPI
+> from fastapiobserver import ObservabilitySettings, install_observability
+>
+> settings = ObservabilitySettings(service="api")
+>
+> @asynccontextmanager
+> async def lifespan(app: FastAPI):
+>     install_observability(app, settings) # Safely initializes per-worker
+>     yield
+>     # fastapiobserver automatically registers shutdown hooks so no teardown needed here
+>
+> app = FastAPI(lifespan=lifespan)
+> ```
+
+#### Prometheus Multiprocess Mode
+
+If you are using Prometheus with multiple Gunicorn workers, you must configure a shared metrics directory:
 
 ```bash
 export PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus-metrics

{fastapi_observer-0.3.1 → fastapi_observer-0.3.2}/src/fastapi_observer.egg-info/requires.txt

@@ -23,6 +23,7 @@ pytest>=9.0.2
 pytest-randomly>=3.16.0
 ruff>=0.15.1
 cyclonedx-bom>=7.2.1
+uvicorn>=0.30.0
 
 [fast-json]
 orjson>=3.11.7

fastapi_observer-0.3.2/src/fastapiobserver/_version.py

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

{fastapi_observer-0.3.1 → fastapi_observer-0.3.2}/src/fastapiobserver/middleware.py

@@ -70,15 +70,15 @@ class RequestLoggingMiddleware:
             return
 
         start = time.perf_counter()
-        headers = _decode_headers(scope.get("headers", []))
-        client_ip, trusted_source = self.ip_resolver.resolve(scope, headers)
-        request_id = self.context_manager.initialize(headers, trusted_source)
+        raw_headers = scope.get("headers", [])
+        client_ip, trusted_source = self.ip_resolver.resolve(scope, raw_headers)
+        request_id = self.context_manager.initialize(raw_headers, trusted_source)
 
         path = scope.get("path", "")
         method = scope.get("method", "UNKNOWN")
         status_code = 500
         captured_error: Exception | None = None
-        request_content_type = headers.get("content-type")
+        request_content_type = _get_header(raw_headers, b"content-type")
         request_body_enabled = self.security_policy.log_request_body and is_body_capturable(
             request_content_type,
             self.security_policy,
@@ -102,17 +102,17 @@ class RequestLoggingMiddleware:
             nonlocal status_code
             if message["type"] == "http.response.start":
                 status_code = int(message.get("status", 500))
-                response_headers = _decode_headers(message.get("headers", []))
+                resp_headers = message.get("headers", [])
                 if (
                     self.security_policy.log_response_body
                     and self.security_policy.body_capture_media_types is not None
                 ):
-                    response_content_type = response_headers.get("content-type")
+                    response_content_type = _get_header(resp_headers, b"content-type")
                     response_body_capture.set_enabled(
                         is_body_capturable(response_content_type, self.security_policy)
                     )
                 updated_headers = _upsert_header(
-                    message.get("headers", []),
+                    resp_headers,
                     self.settings.response_request_id_header,
                     request_id,
                 )
@@ -206,7 +206,11 @@ class _IpResolver:
     def __init__(self, policy: TrustedProxyPolicy) -> None:
         self.policy = policy
 
-    def resolve(self, scope: Scope, headers: dict[str, str]) -> tuple[str | None, bool]:
+    def resolve(
+        self,
+        scope: Scope,
+        headers: list[tuple[bytes, bytes]],
+    ) -> tuple[str | None, bool]:
         scope_client_ip = _extract_scope_client_ip(scope)
         trusted_source = (
             is_trusted_client_ip(scope_client_ip, self.policy)
@@ -220,16 +224,16 @@ class _IpResolver:
 class _RequestContextManager:
     def __init__(self, settings: ObservabilitySettings) -> None:
         self.settings = settings
+        self._request_id_header_bytes = settings.request_id_header.lower().encode("latin1")
 
-    def initialize(self, headers: dict[str, str], trusted_source: bool) -> str:
-        request_id = _resolve_request_id(
-            headers.get(self.settings.request_id_header),
-            trusted_source,
-        )
+    def initialize(self, headers: list[tuple[bytes, bytes]], trusted_source: bool) -> str:
+        request_id_header = _get_header(headers, self._request_id_header_bytes)
+        request_id = _resolve_request_id(request_id_header, trusted_source)
         set_request_id(request_id)
 
         if trusted_source:
-            trace_id, span_id = _parse_traceparent(headers.get("traceparent"))
+            traceparent = _get_header(headers, b"traceparent")
+            trace_id, span_id = _parse_traceparent(traceparent)
             if trace_id:
                 set_trace_id(trace_id)
             if span_id:
@@ -400,11 +404,11 @@ def _upsert_header(
     return next_headers
 
 
-def _decode_headers(headers: list[tuple[bytes, bytes]]) -> dict[str, str]:
-    return {
-        key.decode("latin1").lower(): value.decode("latin1")
-        for key, value in headers
-    }
+def _get_header(headers: list[tuple[bytes, bytes]], target: bytes) -> str | None:
+    for k, v in headers:
+        if k.lower() == target:
+            return v.decode("latin1")
+    return None
 
 
 def _classify_error(status_code: int, error: Exception | None) -> str:

{fastapi_observer-0.3.1 → fastapi_observer-0.3.2}/src/fastapiobserver/security.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import functools
 import hashlib
 import ipaddress
 import os
@@ -464,6 +465,7 @@ def is_body_capturable(content_type: str | None, policy: SecurityPolicy) -> bool
     return False
 
 
+@functools.lru_cache(maxsize=1024)
 def is_trusted_client_ip(client_ip: str | None, policy: TrustedProxyPolicy) -> bool:
     if not policy.enabled:
         return True
@@ -486,14 +488,20 @@ def is_trusted_client_ip(client_ip: str | None, policy: TrustedProxyPolicy) -> b
 
 def resolve_client_ip(
     client_ip: str | None,
-    headers: Mapping[str, str],
+    headers: list[tuple[bytes, bytes]],
     policy: TrustedProxyPolicy,
 ) -> str | None:
     if not policy.honor_forwarded_headers:
         return client_ip
     if not is_trusted_client_ip(client_ip, policy):
         return client_ip
-    forwarded_for = headers.get("x-forwarded-for")
+
+    forwarded_for = None
+    for k, v in headers:
+        if k.lower() == b"x-forwarded-for":
+            forwarded_for = v.decode("latin1")
+            break
+
     if not forwarded_for:
         return client_ip
     first_hop = forwarded_for.split(",")[0].strip()

fastapi_observer-0.3.1/src/fastapiobserver/_version.py

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