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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.3.2
+Version: 0.4.1
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -392,6 +392,19 @@ Request arrives
   -> context cleared
 ```
 
+### Internal Package Layout (Contributor Map)
+
+The project is now organized as focused subpackages instead of large monolithic modules:
+
+- `fastapiobserver/logging/`: formatter, queueing, filters, setup lifecycle, sink circuit-breakers.
+- `fastapiobserver/middleware/`: request logging orchestration, context, IP resolution, headers, body capture, metrics hooks.
+- `fastapiobserver/sinks/`: sink protocol, registry/discovery, built-ins, factory wiring, Logtail + DLQ implementation.
+- `fastapiobserver/metrics/`: backend contracts/registry/builder/endpoint, Prometheus integration subpackage.
+- `fastapiobserver/security/`: policy/settings models, normalization helpers, redaction engine, trusted-proxy utilities.
+- `fastapiobserver/otel/`: OTel settings/resource/tracing/logs/metrics/lifecycle helpers.
+
+Public imports remain backward-compatible via package facades (`__init__.py` re-exports).
+
 ---
 
 ## Example JSON Log Event
@@ -691,6 +704,9 @@ The library supports configuration from code and env vars. Below are the most re
 | `METRICS_EXEMPLARS_ENABLED` | `false` | Enable exemplars where supported |
 | `METRICS_FORMAT` | `negotiate` | `prometheus`, `openmetrics`, or `negotiate` |
 
+> [!CAUTION]
+> The `/metrics` endpoint is **unauthenticated by default**. In production it should be restricted to internal networks (e.g. behind a Kubernetes `NetworkPolicy`, VPC security group, or ingress rule that only allows your Prometheus scraper). Exposing it publicly leaks service topology, error rates, and request patterns.
+
 ### Security and trust boundary
 
 | Variable | Default | Description |
@@ -1028,8 +1044,8 @@ Repository integration tests include:
 
 Reproducible benchmark harness and methodology:
 - Guide: [`benchmarks.md`](benchmarks.md)
-- Apps: `examples/benchmarks/plain_fastapi.py` and `examples/benchmarks/observer_fastapi.py`
-- Runner: `examples/benchmarks/run_local_benchmark.sh`
+- Apps: `examples/benchmarks/app.py`
+- Runner: `examples/benchmarks/harness.py`
 
 ---
 
@@ -1037,9 +1053,10 @@ Reproducible benchmark harness and methodology:
 
 - `0.1.x`: secure-by-default core
 - `0.2.x`: OTel interoperability, security presets, allowlists
+- `0.3.x`: package modularization, sink/metrics hardening, and performance reliability updates
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.3.1`
+Current release version: `0.4.1`
 
 ## Changelog Policy
 
@@ -1094,4 +1111,4 @@ The pre-push hook runs:
 
 ## Roadmap Tracking
 
-See [NEXT_STEPS.md](NEXT_STEPS.md) for the active `0.2.0` roadmap and release checklist.
+See [NEXT_STEPS.md](NEXT_STEPS.md) for the active roadmap and release checklist.

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

@@ -322,6 +322,19 @@ Request arrives
   -> context cleared
 ```
 
+### Internal Package Layout (Contributor Map)
+
+The project is now organized as focused subpackages instead of large monolithic modules:
+
+- `fastapiobserver/logging/`: formatter, queueing, filters, setup lifecycle, sink circuit-breakers.
+- `fastapiobserver/middleware/`: request logging orchestration, context, IP resolution, headers, body capture, metrics hooks.
+- `fastapiobserver/sinks/`: sink protocol, registry/discovery, built-ins, factory wiring, Logtail + DLQ implementation.
+- `fastapiobserver/metrics/`: backend contracts/registry/builder/endpoint, Prometheus integration subpackage.
+- `fastapiobserver/security/`: policy/settings models, normalization helpers, redaction engine, trusted-proxy utilities.
+- `fastapiobserver/otel/`: OTel settings/resource/tracing/logs/metrics/lifecycle helpers.
+
+Public imports remain backward-compatible via package facades (`__init__.py` re-exports).
+
 ---
 
 ## Example JSON Log Event
@@ -621,6 +634,9 @@ The library supports configuration from code and env vars. Below are the most re
 | `METRICS_EXEMPLARS_ENABLED` | `false` | Enable exemplars where supported |
 | `METRICS_FORMAT` | `negotiate` | `prometheus`, `openmetrics`, or `negotiate` |
 
+> [!CAUTION]
+> The `/metrics` endpoint is **unauthenticated by default**. In production it should be restricted to internal networks (e.g. behind a Kubernetes `NetworkPolicy`, VPC security group, or ingress rule that only allows your Prometheus scraper). Exposing it publicly leaks service topology, error rates, and request patterns.
+
 ### Security and trust boundary
 
 | Variable | Default | Description |
@@ -958,8 +974,8 @@ Repository integration tests include:
 
 Reproducible benchmark harness and methodology:
 - Guide: [`benchmarks.md`](benchmarks.md)
-- Apps: `examples/benchmarks/plain_fastapi.py` and `examples/benchmarks/observer_fastapi.py`
-- Runner: `examples/benchmarks/run_local_benchmark.sh`
+- Apps: `examples/benchmarks/app.py`
+- Runner: `examples/benchmarks/harness.py`
 
 ---
 
@@ -967,9 +983,10 @@ Reproducible benchmark harness and methodology:
 
 - `0.1.x`: secure-by-default core
 - `0.2.x`: OTel interoperability, security presets, allowlists
+- `0.3.x`: package modularization, sink/metrics hardening, and performance reliability updates
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.3.1`
+Current release version: `0.4.1`
 
 ## Changelog Policy
 
@@ -1024,4 +1041,4 @@ The pre-push hook runs:
 
 ## Roadmap Tracking
 
-See [NEXT_STEPS.md](NEXT_STEPS.md) for the active `0.2.0` roadmap and release checklist.
+See [NEXT_STEPS.md](NEXT_STEPS.md) for the active roadmap and release checklist.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.3.2
+Version: 0.4.1
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -392,6 +392,19 @@ Request arrives
   -> context cleared
 ```
 
+### Internal Package Layout (Contributor Map)
+
+The project is now organized as focused subpackages instead of large monolithic modules:
+
+- `fastapiobserver/logging/`: formatter, queueing, filters, setup lifecycle, sink circuit-breakers.
+- `fastapiobserver/middleware/`: request logging orchestration, context, IP resolution, headers, body capture, metrics hooks.
+- `fastapiobserver/sinks/`: sink protocol, registry/discovery, built-ins, factory wiring, Logtail + DLQ implementation.
+- `fastapiobserver/metrics/`: backend contracts/registry/builder/endpoint, Prometheus integration subpackage.
+- `fastapiobserver/security/`: policy/settings models, normalization helpers, redaction engine, trusted-proxy utilities.
+- `fastapiobserver/otel/`: OTel settings/resource/tracing/logs/metrics/lifecycle helpers.
+
+Public imports remain backward-compatible via package facades (`__init__.py` re-exports).
+
 ---
 
 ## Example JSON Log Event
@@ -691,6 +704,9 @@ The library supports configuration from code and env vars. Below are the most re
 | `METRICS_EXEMPLARS_ENABLED` | `false` | Enable exemplars where supported |
 | `METRICS_FORMAT` | `negotiate` | `prometheus`, `openmetrics`, or `negotiate` |
 
+> [!CAUTION]
+> The `/metrics` endpoint is **unauthenticated by default**. In production it should be restricted to internal networks (e.g. behind a Kubernetes `NetworkPolicy`, VPC security group, or ingress rule that only allows your Prometheus scraper). Exposing it publicly leaks service topology, error rates, and request patterns.
+
 ### Security and trust boundary
 
 | Variable | Default | Description |
@@ -1028,8 +1044,8 @@ Repository integration tests include:
 
 Reproducible benchmark harness and methodology:
 - Guide: [`benchmarks.md`](benchmarks.md)
-- Apps: `examples/benchmarks/plain_fastapi.py` and `examples/benchmarks/observer_fastapi.py`
-- Runner: `examples/benchmarks/run_local_benchmark.sh`
+- Apps: `examples/benchmarks/app.py`
+- Runner: `examples/benchmarks/harness.py`
 
 ---
 
@@ -1037,9 +1053,10 @@ Reproducible benchmark harness and methodology:
 
 - `0.1.x`: secure-by-default core
 - `0.2.x`: OTel interoperability, security presets, allowlists
+- `0.3.x`: package modularization, sink/metrics hardening, and performance reliability updates
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.3.1`
+Current release version: `0.4.1`
 
 ## Changelog Policy
 
@@ -1094,4 +1111,4 @@ The pre-push hook runs:
 
 ## Roadmap Tracking
 
-See [NEXT_STEPS.md](NEXT_STEPS.md) for the active `0.2.0` roadmap and release checklist.
+See [NEXT_STEPS.md](NEXT_STEPS.md) for the active roadmap and release checklist.

fastapi_observer-0.4.1/src/fastapi_observer.egg-info/SOURCES.txt

@@ -0,0 +1,106 @@
+LICENSE
+README.md
+pyproject.toml
+src/fastapi_observer.egg-info/PKG-INFO
+src/fastapi_observer.egg-info/SOURCES.txt
+src/fastapi_observer.egg-info/dependency_links.txt
+src/fastapi_observer.egg-info/requires.txt
+src/fastapi_observer.egg-info/top_level.txt
+src/fastapiobserver/__init__.py
+src/fastapiobserver/_version.py
+src/fastapiobserver/config.py
+src/fastapiobserver/control_plane.py
+src/fastapiobserver/fastapi.py
+src/fastapiobserver/loguru.py
+src/fastapiobserver/plugins.py
+src/fastapiobserver/propagation.py
+src/fastapiobserver/py.typed
+src/fastapiobserver/request_context.py
+src/fastapiobserver/utils.py
+src/fastapiobserver/integrations/__init__.py
+src/fastapiobserver/integrations/strawberry.py
+src/fastapiobserver/logging/__init__.py
+src/fastapiobserver/logging/circuit_breaker.py
+src/fastapiobserver/logging/filters.py
+src/fastapiobserver/logging/formatter.py
+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/middleware/__init__.py
+src/fastapiobserver/middleware/body_capture.py
+src/fastapiobserver/middleware/context.py
+src/fastapiobserver/middleware/events.py
+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/lifecycle.py
+src/fastapiobserver/otel/logs.py
+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
+src/fastapiobserver/security/proxies.py
+src/fastapiobserver/security/redaction.py
+src/fastapiobserver/sinks/__init__.py
+src/fastapiobserver/sinks/builtin.py
+src/fastapiobserver/sinks/discovery.py
+src/fastapiobserver/sinks/factory.py
+src/fastapiobserver/sinks/protocol.py
+src/fastapiobserver/sinks/registry.py
+src/fastapiobserver/sinks/stats.py
+src/fastapiobserver/sinks/logtail/__init__.py
+src/fastapiobserver/sinks/logtail/dlq.py
+src/fastapiobserver/sinks/logtail/handler.py
+src/fastapiobserver/sinks/logtail/sink.py
+tests/test_body_media_allowlist.py
+tests/test_config_settings.py
+tests/test_dx_parity.py
+tests/test_excluded_url_precedence.py
+tests/test_fastapi_install.py
+tests/test_graphql_integrations.py
+tests/test_log_queue_controls.py
+tests/test_logging_schema_contract.py
+tests/test_logtail_dlq.py
+tests/test_loguru_bridge.py
+tests/test_metrics_contracts.py
+tests/test_metrics_optional_dependency.py
+tests/test_middleware.py
+tests/test_negotiate_content_type.py
+tests/test_otel_integration.py
+tests/test_otel_lifecycle.py
+tests/test_otel_log_correlation.py
+tests/test_otel_logs_from_env.py
+tests/test_otel_logs_pipeline.py
+tests/test_otel_metrics_from_env.py
+tests/test_otlp_export_integration.py
+tests/test_plugin_isolation.py
+tests/test_propagation.py
+tests/test_redaction_presets.py
+tests/test_route_template_cardinality.py
+tests/test_runtime_control_auth.py
+tests/test_security_audit_fixes.py
+tests/test_security_redaction.py
+tests/test_sink_circuit_breaker.py
+tests/test_sinks.py
+tests/test_trust_boundary.py
+tests/test_utils_refactors.py

fastapi_observer-0.4.1/src/fastapiobserver/_version.py

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

{fastapi_observer-0.3.2 → fastapi_observer-0.4.1}/src/fastapiobserver/control_plane.py

@@ -72,7 +72,13 @@ def mount_control_plane(app: FastAPI, settings: RuntimeControlSettings) -> None:
     def authorize(
         authorization: Annotated[str | None, Header()] = None,
     ) -> None:
-        expected = f"Bearer {token}"
+        current_token = os.getenv(settings.token_env_var)
+        if not current_token:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Unauthorized",
+            )
+        expected = f"Bearer {current_token}"
         if not authorization or not secrets.compare_digest(authorization, expected):
             raise HTTPException(
                 status_code=status.HTTP_401_UNAUTHORIZED,

fastapi_observer-0.4.1/src/fastapiobserver/logging/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from .circuit_breaker import (
+    CircuitBreakerState,
+    SinkCircuitBreakerHandler,
+    SinkCircuitBreakerSnapshot,
+    get_sink_circuit_breaker_stats,
+)
+from .filters import PluginLogFilter, RequestIdFilter, TraceContextFilter
+from .formatter import LOG_SCHEMA_VERSION, StructuredJsonFormatter
+from .queueing import (
+    LogQueueStatsSnapshot,
+    LogQueueTelemetry,
+    OverflowPolicyQueueHandler,
+    get_log_queue_stats,
+)
+from .setup import get_managed_output_handlers, setup_logging, shutdown_logging
+
+__all__ = [
+    "LOG_SCHEMA_VERSION",
+    "CircuitBreakerState",
+    "LogQueueStatsSnapshot",
+    "LogQueueTelemetry",
+    "OverflowPolicyQueueHandler",
+    "PluginLogFilter",
+    "RequestIdFilter",
+    "SinkCircuitBreakerHandler",
+    "SinkCircuitBreakerSnapshot",
+    "StructuredJsonFormatter",
+    "TraceContextFilter",
+    "get_log_queue_stats",
+    "get_managed_output_handlers",
+    "get_sink_circuit_breaker_stats",
+    "setup_logging",
+    "shutdown_logging",
+]

fastapi_observer-0.4.1/src/fastapiobserver/logging/circuit_breaker.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Callable, Literal
+
+CircuitBreakerState = Literal["closed", "open", "half_open"]
+
+
+@dataclass(frozen=True)
+class SinkCircuitBreakerSnapshot:
+    sink_name: str
+    state: CircuitBreakerState
+    failure_threshold: int
+    recovery_timeout_seconds: float
+    consecutive_failures: int
+    handled_total: int
+    failures_total: int
+    skipped_total: int
+    opens_total: int
+    half_open_total: int
+    closes_total: int
+
+    def as_dict(self) -> dict[str, int | float | str]:
+        return {
+            "sink_name": self.sink_name,
+            "state": self.state,
+            "failure_threshold": self.failure_threshold,
+            "recovery_timeout_seconds": self.recovery_timeout_seconds,
+            "consecutive_failures": self.consecutive_failures,
+            "handled_total": self.handled_total,
+            "failures_total": self.failures_total,
+            "skipped_total": self.skipped_total,
+            "opens_total": self.opens_total,
+            "half_open_total": self.half_open_total,
+            "closes_total": self.closes_total,
+        }
+
+
+class SinkCircuitBreakerHandler(logging.Handler):
+    """Protect sink handlers with a basic open/half-open/closed breaker."""
+
+    def __init__(
+        self,
+        *,
+        sink_name: str,
+        delegate: logging.Handler,
+        failure_threshold: int,
+        recovery_timeout_seconds: float,
+        clock: Callable[[], float] | None = None,
+    ) -> None:
+        super().__init__(level=delegate.level)
+        self.sink_name = sink_name
+        self._delegate = delegate
+        self._failure_threshold = max(1, int(failure_threshold))
+        self._recovery_timeout_seconds = max(0.001, float(recovery_timeout_seconds))
+        self._clock = clock or time.monotonic
+        self._lock = threading.Lock()
+
+        self._state: CircuitBreakerState = "closed"
+        self._opened_until = 0.0
+        self._consecutive_failures = 0
+        self._handled_total = 0
+        self._failures_total = 0
+        self._skipped_total = 0
+        self._opens_total = 0
+        self._half_open_total = 0
+        self._closes_total = 0
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if self._should_skip():
+            return
+
+        try:
+            self._delegate.handle(record)
+        except Exception:
+            self._record_failure()
+            self.handleError(record)
+            return
+
+        self._record_success()
+
+    def setFormatter(self, fmt: logging.Formatter | None) -> None:  # noqa: N802
+        super().setFormatter(fmt)
+        self._delegate.setFormatter(fmt)
+
+    def flush(self) -> None:
+        self._delegate.flush()
+
+    def close(self) -> None:
+        try:
+            self._delegate.close()
+        finally:
+            super().close()
+
+    def snapshot(self) -> SinkCircuitBreakerSnapshot:
+        with self._lock:
+            return SinkCircuitBreakerSnapshot(
+                sink_name=self.sink_name,
+                state=self._state,
+                failure_threshold=self._failure_threshold,
+                recovery_timeout_seconds=self._recovery_timeout_seconds,
+                consecutive_failures=self._consecutive_failures,
+                handled_total=self._handled_total,
+                failures_total=self._failures_total,
+                skipped_total=self._skipped_total,
+                opens_total=self._opens_total,
+                half_open_total=self._half_open_total,
+                closes_total=self._closes_total,
+            )
+
+    def _should_skip(self) -> bool:
+        with self._lock:
+            now = self._clock()
+            if self._state != "open":
+                return False
+            if now >= self._opened_until:
+                self._state = "half_open"
+                self._half_open_total += 1
+                return False
+            self._skipped_total += 1
+            return True
+
+    def _record_failure(self) -> None:
+        with self._lock:
+            now = self._clock()
+            self._failures_total += 1
+            self._consecutive_failures += 1
+
+            should_open = (
+                self._state == "half_open"
+                or self._consecutive_failures >= self._failure_threshold
+            )
+            if should_open:
+                self._state = "open"
+                self._opens_total += 1
+                self._opened_until = now + self._recovery_timeout_seconds
+                self._consecutive_failures = 0
+
+    def _record_success(self) -> None:
+        with self._lock:
+            self._handled_total += 1
+            self._consecutive_failures = 0
+            if self._state == "half_open":
+                self._state = "closed"
+                self._closes_total += 1
+                self._opened_until = 0.0
+
+
+def get_sink_circuit_breaker_stats() -> dict[str, dict[str, int | float | str]]:
+    """Return per-sink circuit-breaker snapshots."""
+    from .state import _LOGGING_LOCK, _SINK_CIRCUIT_BREAKERS
+
+    with _LOGGING_LOCK:
+        breakers = list(_SINK_CIRCUIT_BREAKERS)
+    return {breaker.sink_name: breaker.snapshot().as_dict() for breaker in breakers}

fastapi_observer-0.4.1/src/fastapiobserver/logging/filters.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import logging
+
+from ..plugins import apply_log_filters
+from ..request_context import get_request_id, get_span_id, get_trace_id
+
+_LOGGER = logging.getLogger("fastapiobserver.logging")
+
+
+class RequestIdFilter(logging.Filter):
+    """Attach request ID from context vars to every log record."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if not getattr(record, "request_id", None):
+            record.request_id = get_request_id()
+        return True
+
+
+class TraceContextFilter(logging.Filter):
+    """Attach OTel trace_id / span_id to every log record."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        trace_id = get_trace_id()
+        span_id = get_span_id()
+
+        try:
+            from opentelemetry import trace as otel_trace  # type: ignore
+
+            span = otel_trace.get_current_span()
+            span_context = span.get_span_context()
+            if span_context and span_context.is_valid:
+                trace_id = f"{span_context.trace_id:032x}"
+                span_id = f"{span_context.span_id:016x}"
+        except Exception:
+            _LOGGER.debug(
+                "trace_context_filter.otel_lookup_failed",
+                exc_info=True,
+                extra={"_skip_enrichers": True},
+            )
+
+        if trace_id:
+            record.trace_id = trace_id  # type: ignore[attr-defined]
+        if span_id:
+            record.span_id = span_id  # type: ignore[attr-defined]
+        return True
+
+
+class PluginLogFilter(logging.Filter):
+    """Apply user-registered log filters with fault isolation."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return apply_log_filters(record)