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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.3.2
+Version: 0.4.0
 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
@@ -1037,9 +1050,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.0`
 
 ## Changelog Policy
 
@@ -1094,4 +1108,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.0}/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
@@ -967,9 +980,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.0`
 
 ## Changelog Policy
 
@@ -1024,4 +1038,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.0/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.0
 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
@@ -1037,9 +1050,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.0`
 
 ## Changelog Policy
 
@@ -1094,4 +1108,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.0/src/fastapi_observer.egg-info/SOURCES.txt

@@ -0,0 +1,104 @@
+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_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_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.0/src/fastapiobserver/_version.py

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

{fastapi_observer-0.3.2 → fastapi_observer-0.4.0}/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.0/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.0/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.0/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)

fastapi_observer-0.4.0/src/fastapiobserver/logging/formatter.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import re
+from datetime import datetime, timezone
+from typing import Any, Callable, Mapping
+
+from .._version import __version__
+from ..config import ObservabilitySettings
+from ..plugins import apply_log_enrichers
+from ..request_context import get_request_id, get_span_id, get_trace_id, get_user_context
+from ..security import SecurityPolicy, sanitize_event
+from ..utils import lazy_import
+
+orjson: Any
+try:
+    orjson = lazy_import("orjson")
+except ModuleNotFoundError:  # pragma: no cover
+    orjson = None
+
+LOG_SCHEMA_VERSION = "1.0.0"
+
+
+class StructuredJsonFormatter(logging.Formatter):
+    """Serialize log records into structured JSON.
+
+    Fields include service identity, request ID, trace/span IDs for
+    correlation, and user context.  Plugin enrichers are applied unless
+    the record has ``_skip_enrichers`` set.
+    """
+
+    def __init__(
+        self,
+        settings: ObservabilitySettings,
+        security_policy: SecurityPolicy | None = None,
+        *,
+        enrich_event: (
+            Callable[[dict[str, object]], Mapping[str, object] | dict[str, object]] | None
+        ) = None,
+        sanitize_payload: (
+            Callable[[dict[str, Any], SecurityPolicy], Mapping[str, Any] | dict[str, Any]]
+            | None
+        ) = None,
+    ) -> None:
+        super().__init__()
+        self.settings = settings
+        self.security_policy = security_policy or SecurityPolicy()
+        self._enrich_event = enrich_event or apply_log_enrichers
+        self._sanitize_payload = sanitize_payload or sanitize_event
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "app_name": self.settings.app_name,
+            "service": self.settings.service,
+            "environment": self.settings.environment,
+            "version": self.settings.version,
+            "log_schema_version": LOG_SCHEMA_VERSION,
+            "library": "fastapiobserver",
+            "library_version": __version__,
+        }
+
+        request_id = getattr(record, "request_id", None) or get_request_id()
+        if request_id:
+            payload["request_id"] = request_id
+
+        trace_id = getattr(record, "trace_id", None) or get_trace_id()
+        if trace_id:
+            payload["trace_id"] = trace_id
+
+        span_id = getattr(record, "span_id", None) or get_span_id()
+        if span_id:
+            payload["span_id"] = span_id
+
+        user_context = get_user_context()
+        if user_context:
+            payload["user_context"] = user_context
+
+        event = getattr(record, "event", None)
+        if isinstance(event, dict):
+            payload["event"] = event
+
+        if record.exc_info:
+            error_payload = _build_structured_error(record, self)
+            payload["error"] = error_payload
+            # Backward-compatible field retained for existing dashboards.
+            payload["exc_info"] = error_payload["stacktrace"]
+
+        if getattr(record, "_skip_enrichers", False):
+            enriched_payload = payload
+        else:
+            candidate_payload = self._enrich_event(dict(payload))
+            if isinstance(candidate_payload, Mapping):
+                enriched_payload = dict(candidate_payload)
+            else:
+                enriched_payload = payload
+        sanitized_candidate = self._sanitize_payload(enriched_payload, self.security_policy)
+        if isinstance(sanitized_candidate, Mapping):
+            sanitized_payload = dict(sanitized_candidate)
+        else:
+            sanitized_payload = enriched_payload
+        return _json_dumps(sanitized_payload)
+
+
+def _json_dumps(payload: dict[str, Any]) -> str:
+    if orjson is not None:
+        return orjson.dumps(payload).decode("utf-8")
+    return json.dumps(payload, ensure_ascii=True, default=str)
+
+
+def _build_structured_error(
+    record: logging.LogRecord,
+    formatter: logging.Formatter,
+) -> dict[str, str]:
+    exc_info = record.exc_info
+    if not exc_info:
+        return {"type": "", "message": "", "stacktrace": ""}
+
+    if not isinstance(exc_info, tuple) or len(exc_info) != 3:
+        return {
+            "type": "Exception",
+            "message": "",
+            "stacktrace": "",
+        }
+
+    exc_type, exc_value, _exc_tb = exc_info
+    error_type = exc_type.__name__ if exc_type is not None else "Exception"
+    error_message = str(exc_value) if exc_value is not None else ""
+    stacktrace = formatter.formatException(exc_info)
+    fingerprint = _generate_error_fingerprint(error_type, stacktrace)
+
+    return {
+        "type": error_type,
+        "message": error_message,
+        "stacktrace": stacktrace,
+        "fingerprint": fingerprint,
+    }
+
+
+def _generate_error_fingerprint(error_type: str, stacktrace: str) -> str:
+    """Hash stack trace after stripping out environment-specific noise."""
+    if not stacktrace:
+        return hashlib.md5(error_type.encode("utf-8")).hexdigest()
+
+    # Strip hexadecimal memory addresses
+    sanitized = re.sub(r"0x[0-9a-fA-F]+", "0x<ptr>", stacktrace)
+    # Strip exact line numbers to survive minor file refactoring
+    sanitized = re.sub(r"line \d+", "line <N>", sanitized)
+    
+    # Combine error type and sanitized trace to ensure distinct groupings
+    payload = f"{error_type}:{sanitized}"
+    return hashlib.md5(payload.encode("utf-8")).hexdigest()