fastapi-observer 0.2.5__tar.gz → 0.3.0__tar.gz

{fastapi_observer-0.2.5/src/fastapi_observer.egg-info → fastapi_observer-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.2.5
+Version: 0.3.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Framework :: FastAPI
 Classifier: Topic :: System :: Logging
 Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -423,14 +424,15 @@ Request arrives
 }
 ```
 
-On exception logs, a structured `error` object is included for indexed queries:
+On exception logs, a structured `error` object is included for indexed queries, featuring a stable AST-based `fingerprint` hash which ignores transient memory locations or exact line numbers, allowing zero-dependency alerting directly in your search backend.
 
 ```json
 {
   "error": {
     "type": "RuntimeError",
     "message": "boom",
-    "stacktrace": "Traceback (most recent call last): ..."
+    "stacktrace": "Traceback (most recent call last): ...",
+    "fingerprint": "a1b2c3d4e5f67890abcd12345678bbcc"
   }
 }
 ```
@@ -583,6 +585,7 @@ The `examples/` directory contains runnable demos:
 | [`security_presets_app.py`](examples/security_presets_app.py) | Preset-based security policy |
 | [`allowlist_app.py`](examples/allowlist_app.py) | Allowlist-only sanitization |
 | [`otel_app.py`](examples/otel_app.py) | OTel tracing and resource attributes |
+| [`graphql_app.py`](examples/graphql_app.py) | Native Strawberry GraphQL observability |
 | [`benchmarks/`](examples/benchmarks/) | Baseline vs observer benchmark harness |
 | [`k8s/`](examples/k8s/) | Kubernetes-native stack with Prometheus + Loki + Tempo + Grafana |
 | [`full_stack/`](examples/full_stack/) | **Docker Compose stack**: 3 FastAPI services + Grafana + Prometheus + Loki + Tempo |
@@ -702,6 +705,13 @@ Notes:
 | `LOGTAIL_SOURCE_TOKEN` | - | Logtail source token |
 | `LOGTAIL_BATCH_SIZE` | `50` | Batch size for shipping |
 | `LOGTAIL_FLUSH_INTERVAL` | `2.0` | Flush interval (seconds) |
+| `LOGTAIL_DLQ_ENABLED` | `false` | Enable resilient local disk fallback for dropped logs |
+| `LOGTAIL_DLQ_DIR` | `.dlq/logtail` | Directory to archive dropped NDJSON messages |
+| `LOGTAIL_DLQ_MAX_BYTES` | `52428800` | Max bytes per DLQ file before rotation (50MB) |
+| `LOGTAIL_DLQ_COMPRESS` | `true` | GZIP compress rotated DLQ files |
+
+> [!TIP]
+> The Logtail Dead Letter Queue (DLQ) provides best-effort local durability. If the internal memory queue overflows under immense API pressure (`queue.Full`), or if an external network partition completely exhausts the outbound HTTP retry backoff, the dropped log payloads are immediately salvaged into local NDJSON envelopes. You can replay these files to BetterStack later using the provided `scripts/replay_dlq.py` utility.
 
 ---
 
@@ -818,6 +828,45 @@ Detailed migration/coexistence guide: [`loguru.md`](loguru.md)
 
 ---
 
+## GraphQL Integrations (Strawberry)
+
+If you use `strawberry-graphql`, routing all traffic through `POST /graphql` severely blinds your logs and traces.
+`fastapi-observer` ships a native Strawberry extension (via Duck Typing, meaning NO bloated pip dependencies) to automatically extract GraphQL operations.
+
+```python
+import strawberry
+from fastapiobserver.integrations.strawberry import StrawberryObservabilityExtension
+
+@strawberry.type
+class Query:
+    @strawberry.field
+    def hello(self) -> str:
+        return "world"
+
+schema = strawberry.Schema(
+    query=Query,
+    extensions=[StrawberryObservabilityExtension],  # Inject this!
+)
+```
+
+With this extension, your logs will automatically get a `graphql` context key containing the extracted `operation_name`:
+```json
+{
+  "event": {
+    "method": "POST",
+    "path": "/graphql"
+  },
+  "user_context": {
+    "graphql": {
+      "operation_name": "GetUsersQuery"
+    }
+  }
+}
+```
+If OpenTelemetry is enabled, your traces will dynamically rename from `POST /graphql` to `graphql.operation.GetUsersQuery`.
+
+---
+
 ## Plugin Hooks
 
 Extend behavior without editing package internals:
@@ -914,7 +963,7 @@ Reproducible benchmark harness and methodology:
 - `0.2.x`: OTel interoperability, security presets, allowlists
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.2.5`
+Current release version: `0.3.0`
 
 ## Changelog Policy
 

{fastapi_observer-0.2.5 → fastapi_observer-0.3.0}/README.md

@@ -355,14 +355,15 @@ Request arrives
 }
 ```
 
-On exception logs, a structured `error` object is included for indexed queries:
+On exception logs, a structured `error` object is included for indexed queries, featuring a stable AST-based `fingerprint` hash which ignores transient memory locations or exact line numbers, allowing zero-dependency alerting directly in your search backend.
 
 ```json
 {
   "error": {
     "type": "RuntimeError",
     "message": "boom",
-    "stacktrace": "Traceback (most recent call last): ..."
+    "stacktrace": "Traceback (most recent call last): ...",
+    "fingerprint": "a1b2c3d4e5f67890abcd12345678bbcc"
   }
 }
 ```
@@ -515,6 +516,7 @@ The `examples/` directory contains runnable demos:
 | [`security_presets_app.py`](examples/security_presets_app.py) | Preset-based security policy |
 | [`allowlist_app.py`](examples/allowlist_app.py) | Allowlist-only sanitization |
 | [`otel_app.py`](examples/otel_app.py) | OTel tracing and resource attributes |
+| [`graphql_app.py`](examples/graphql_app.py) | Native Strawberry GraphQL observability |
 | [`benchmarks/`](examples/benchmarks/) | Baseline vs observer benchmark harness |
 | [`k8s/`](examples/k8s/) | Kubernetes-native stack with Prometheus + Loki + Tempo + Grafana |
 | [`full_stack/`](examples/full_stack/) | **Docker Compose stack**: 3 FastAPI services + Grafana + Prometheus + Loki + Tempo |
@@ -634,6 +636,13 @@ Notes:
 | `LOGTAIL_SOURCE_TOKEN` | - | Logtail source token |
 | `LOGTAIL_BATCH_SIZE` | `50` | Batch size for shipping |
 | `LOGTAIL_FLUSH_INTERVAL` | `2.0` | Flush interval (seconds) |
+| `LOGTAIL_DLQ_ENABLED` | `false` | Enable resilient local disk fallback for dropped logs |
+| `LOGTAIL_DLQ_DIR` | `.dlq/logtail` | Directory to archive dropped NDJSON messages |
+| `LOGTAIL_DLQ_MAX_BYTES` | `52428800` | Max bytes per DLQ file before rotation (50MB) |
+| `LOGTAIL_DLQ_COMPRESS` | `true` | GZIP compress rotated DLQ files |
+
+> [!TIP]
+> The Logtail Dead Letter Queue (DLQ) provides best-effort local durability. If the internal memory queue overflows under immense API pressure (`queue.Full`), or if an external network partition completely exhausts the outbound HTTP retry backoff, the dropped log payloads are immediately salvaged into local NDJSON envelopes. You can replay these files to BetterStack later using the provided `scripts/replay_dlq.py` utility.
 
 ---
 
@@ -750,6 +759,45 @@ Detailed migration/coexistence guide: [`loguru.md`](loguru.md)
 
 ---
 
+## GraphQL Integrations (Strawberry)
+
+If you use `strawberry-graphql`, routing all traffic through `POST /graphql` severely blinds your logs and traces.
+`fastapi-observer` ships a native Strawberry extension (via Duck Typing, meaning NO bloated pip dependencies) to automatically extract GraphQL operations.
+
+```python
+import strawberry
+from fastapiobserver.integrations.strawberry import StrawberryObservabilityExtension
+
+@strawberry.type
+class Query:
+    @strawberry.field
+    def hello(self) -> str:
+        return "world"
+
+schema = strawberry.Schema(
+    query=Query,
+    extensions=[StrawberryObservabilityExtension],  # Inject this!
+)
+```
+
+With this extension, your logs will automatically get a `graphql` context key containing the extracted `operation_name`:
+```json
+{
+  "event": {
+    "method": "POST",
+    "path": "/graphql"
+  },
+  "user_context": {
+    "graphql": {
+      "operation_name": "GetUsersQuery"
+    }
+  }
+}
+```
+If OpenTelemetry is enabled, your traces will dynamically rename from `POST /graphql` to `graphql.operation.GetUsersQuery`.
+
+---
+
 ## Plugin Hooks
 
 Extend behavior without editing package internals:
@@ -846,7 +894,7 @@ Reproducible benchmark harness and methodology:
 - `0.2.x`: OTel interoperability, security presets, allowlists
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.2.5`
+Current release version: `0.3.0`
 
 ## Changelog Policy
 

{fastapi_observer-0.2.5 → fastapi_observer-0.3.0}/pyproject.toml

@@ -24,6 +24,7 @@ classifiers = [
     "Framework :: FastAPI",
     "Topic :: System :: Logging",
     "Topic :: System :: Monitoring",
+    "Typing :: Typed",
 ]
 keywords = ["fastapi", "observability", "logging", "metrics", "opentelemetry"]
 license = "MIT"
@@ -114,3 +115,4 @@ ignore_missing_imports = true
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]
+asyncio_mode = "auto"

{fastapi_observer-0.2.5 → fastapi_observer-0.3.0/src/fastapi_observer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-observer
-Version: 0.2.5
+Version: 0.3.0
 Summary: Zero-glue FastAPI observability with security presets and runtime controls
 Author-email: Vitaee <opensource@vitaee.dev>
 License-Expression: MIT
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Framework :: FastAPI
 Classifier: Topic :: System :: Logging
 Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -423,14 +424,15 @@ Request arrives
 }
 ```
 
-On exception logs, a structured `error` object is included for indexed queries:
+On exception logs, a structured `error` object is included for indexed queries, featuring a stable AST-based `fingerprint` hash which ignores transient memory locations or exact line numbers, allowing zero-dependency alerting directly in your search backend.
 
 ```json
 {
   "error": {
     "type": "RuntimeError",
     "message": "boom",
-    "stacktrace": "Traceback (most recent call last): ..."
+    "stacktrace": "Traceback (most recent call last): ...",
+    "fingerprint": "a1b2c3d4e5f67890abcd12345678bbcc"
   }
 }
 ```
@@ -583,6 +585,7 @@ The `examples/` directory contains runnable demos:
 | [`security_presets_app.py`](examples/security_presets_app.py) | Preset-based security policy |
 | [`allowlist_app.py`](examples/allowlist_app.py) | Allowlist-only sanitization |
 | [`otel_app.py`](examples/otel_app.py) | OTel tracing and resource attributes |
+| [`graphql_app.py`](examples/graphql_app.py) | Native Strawberry GraphQL observability |
 | [`benchmarks/`](examples/benchmarks/) | Baseline vs observer benchmark harness |
 | [`k8s/`](examples/k8s/) | Kubernetes-native stack with Prometheus + Loki + Tempo + Grafana |
 | [`full_stack/`](examples/full_stack/) | **Docker Compose stack**: 3 FastAPI services + Grafana + Prometheus + Loki + Tempo |
@@ -702,6 +705,13 @@ Notes:
 | `LOGTAIL_SOURCE_TOKEN` | - | Logtail source token |
 | `LOGTAIL_BATCH_SIZE` | `50` | Batch size for shipping |
 | `LOGTAIL_FLUSH_INTERVAL` | `2.0` | Flush interval (seconds) |
+| `LOGTAIL_DLQ_ENABLED` | `false` | Enable resilient local disk fallback for dropped logs |
+| `LOGTAIL_DLQ_DIR` | `.dlq/logtail` | Directory to archive dropped NDJSON messages |
+| `LOGTAIL_DLQ_MAX_BYTES` | `52428800` | Max bytes per DLQ file before rotation (50MB) |
+| `LOGTAIL_DLQ_COMPRESS` | `true` | GZIP compress rotated DLQ files |
+
+> [!TIP]
+> The Logtail Dead Letter Queue (DLQ) provides best-effort local durability. If the internal memory queue overflows under immense API pressure (`queue.Full`), or if an external network partition completely exhausts the outbound HTTP retry backoff, the dropped log payloads are immediately salvaged into local NDJSON envelopes. You can replay these files to BetterStack later using the provided `scripts/replay_dlq.py` utility.
 
 ---
 
@@ -818,6 +828,45 @@ Detailed migration/coexistence guide: [`loguru.md`](loguru.md)
 
 ---
 
+## GraphQL Integrations (Strawberry)
+
+If you use `strawberry-graphql`, routing all traffic through `POST /graphql` severely blinds your logs and traces.
+`fastapi-observer` ships a native Strawberry extension (via Duck Typing, meaning NO bloated pip dependencies) to automatically extract GraphQL operations.
+
+```python
+import strawberry
+from fastapiobserver.integrations.strawberry import StrawberryObservabilityExtension
+
+@strawberry.type
+class Query:
+    @strawberry.field
+    def hello(self) -> str:
+        return "world"
+
+schema = strawberry.Schema(
+    query=Query,
+    extensions=[StrawberryObservabilityExtension],  # Inject this!
+)
+```
+
+With this extension, your logs will automatically get a `graphql` context key containing the extracted `operation_name`:
+```json
+{
+  "event": {
+    "method": "POST",
+    "path": "/graphql"
+  },
+  "user_context": {
+    "graphql": {
+      "operation_name": "GetUsersQuery"
+    }
+  }
+}
+```
+If OpenTelemetry is enabled, your traces will dynamically rename from `POST /graphql` to `graphql.operation.GetUsersQuery`.
+
+---
+
 ## Plugin Hooks
 
 Extend behavior without editing package internals:
@@ -914,7 +963,7 @@ Reproducible benchmark harness and methodology:
 - `0.2.x`: OTel interoperability, security presets, allowlists
 - `1.0.0`: dynamic runtime controls and plugin stability
 
-Current release version: `0.2.5`
+Current release version: `0.3.0`
 
 ## Changelog Policy
 

{fastapi_observer-0.2.5 → fastapi_observer-0.3.0}/src/fastapi_observer.egg-info/SOURCES.txt

@@ -22,6 +22,8 @@ src/fastapiobserver/request_context.py
 src/fastapiobserver/security.py
 src/fastapiobserver/sinks.py
 src/fastapiobserver/utils.py
+src/fastapiobserver/integrations/__init__.py
+src/fastapiobserver/integrations/strawberry.py
 src/fastapiobserver/otel/__init__.py
 src/fastapiobserver/otel/lifecycle.py
 src/fastapiobserver/otel/logs.py
@@ -34,8 +36,10 @@ 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_optional_dependency.py
 tests/test_middleware.py
@@ -54,5 +58,6 @@ 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.3.0/src/fastapiobserver/_version.py

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

{fastapi_observer-0.2.5 → fastapi_observer-0.3.0}/src/fastapiobserver/config.py

@@ -103,6 +103,28 @@ class ObservabilitySettings(BaseSettings):
         default=2.0, gt=0.0, validation_alias="LOGTAIL_FLUSH_INTERVAL"
     )
 
+    # --- logtail DLQ ---
+    logtail_dlq_enabled: bool = Field(
+        default=False, validation_alias="LOGTAIL_DLQ_ENABLED"
+    )
+    logtail_dlq_dir: str = Field(
+        default=".dlq/logtail", validation_alias="LOGTAIL_DLQ_DIR"
+    )
+    logtail_dlq_filename: str = Field(
+        default="logtail_dlq.ndjson",
+        validation_alias="LOGTAIL_DLQ_FILENAME",
+    )
+    logtail_dlq_max_bytes: int = Field(
+        default=50 * 1024 * 1024,
+        validation_alias="LOGTAIL_DLQ_MAX_BYTES",
+    )
+    logtail_dlq_backup_count: int = Field(
+        default=10, validation_alias="LOGTAIL_DLQ_BACKUP_COUNT"
+    )
+    logtail_dlq_compress: bool = Field(
+        default=True, validation_alias="LOGTAIL_DLQ_COMPRESS"
+    )
+
     # ---------- validators ----------
 
     @field_validator("log_level")

{fastapi_observer-0.2.5 → fastapi_observer-0.3.0}/src/fastapiobserver/control_plane.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 import os
 import secrets
+import weakref
 from typing import Annotated, Literal
 
 from fastapi import APIRouter, Depends, FastAPI, Header, HTTPException, status
@@ -12,6 +13,13 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 from .otel import get_trace_sampling_ratio, set_trace_sampling_ratio
 from .utils import EnvLoadable, normalize_path
 
+__all__ = [
+    "RuntimeControlSettings",
+    "ControlPlanePayload",
+    "mount_control_plane",
+]
+
+_MOUNTED_CONTROL_PATHS: weakref.WeakKeyDictionary[FastAPI, set[str]] = weakref.WeakKeyDictionary()
 
 class RuntimeControlSettings(EnvLoadable, BaseModel):
     model_config = ConfigDict(frozen=True)
@@ -57,9 +65,7 @@ def mount_control_plane(app: FastAPI, settings: RuntimeControlSettings) -> None:
         )
 
     normalized_path = settings.path
-    mounted_paths: set[str] = getattr(
-        app.state, "_fastapiobserver_control_paths", set()
-    )
+    mounted_paths = _MOUNTED_CONTROL_PATHS.setdefault(app, set())
     if normalized_path in mounted_paths:
         return
 
@@ -93,7 +99,6 @@ def mount_control_plane(app: FastAPI, settings: RuntimeControlSettings) -> None:
 
     app.include_router(router)
     mounted_paths.add(normalized_path)
-    app.state._fastapiobserver_control_paths = mounted_paths
 
 
 def _current_runtime_settings() -> dict[str, object]:

{fastapi_observer-0.2.5 → fastapi_observer-0.3.0}/src/fastapiobserver/fastapi.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 import logging
+import weakref
+import typing
+from contextlib import asynccontextmanager
 from typing import Literal
 
 from fastapi import FastAPI
@@ -24,7 +27,7 @@ from .otel import (
 from .security import SecurityPolicy, TrustedProxyPolicy
 
 _LOGGER = logging.getLogger("fastapiobserver.fastapi")
-_LOGGING_SHUTDOWN_HOOK_ATTR = "_fastapiobserver_logging_shutdown_hook_registered"
+_REGISTERED_APPS: weakref.WeakSet[FastAPI] = weakref.WeakSet()
 
 
 def install_observability(
@@ -156,7 +159,19 @@ def _has_request_logging_middleware(app: FastAPI) -> bool:
 
 
 def _register_logging_shutdown_hook(app: FastAPI) -> None:
-    if bool(getattr(app.state, _LOGGING_SHUTDOWN_HOOK_ATTR, False)):
+    if app in _REGISTERED_APPS:
         return
-    app.add_event_handler("shutdown", shutdown_logging)
-    setattr(app.state, _LOGGING_SHUTDOWN_HOOK_ATTR, True)
+
+    original_lifespan = app.router.lifespan_context
+
+    @asynccontextmanager
+    async def observability_lifespan(app_inst: FastAPI) -> typing.AsyncGenerator[typing.Any, None]:
+        if original_lifespan:
+            async with original_lifespan(app_inst) as state:
+                yield state
+        else:
+            yield {}
+        shutdown_logging()
+
+    app.router.lifespan_context = observability_lifespan
+    _REGISTERED_APPS.add(app)

fastapi_observer-0.3.0/src/fastapiobserver/integrations/strawberry.py

@@ -0,0 +1,78 @@
+"""Strawberry GraphQL integration for fastapi-observer.
+
+This module provides a `StrawberryObservabilityExtension` that automatically
+extracts the `operationName` from incoming GraphQL requests and injects it
+into the active `fastapiobserver` telemetry context, as well as setting the
+OpenTelemetry span name if active.
+
+It does NOT require `strawberry-graphql` as a hard dependency. It uses Duck Typing.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..request_context import get_user_context, set_user_context
+
+_LOGGER = logging.getLogger("fastapiobserver.integrations.strawberry")
+
+
+class StrawberryObservabilityExtension:
+    """Strawberry SchemaExtension for injecting operation names into logs/traces.
+
+    Usage:
+        import strawberry
+        from fastapiobserver.integrations.strawberry import StrawberryObservabilityExtension
+
+        schema = strawberry.Schema(
+            query=Query,
+            extensions=[StrawberryObservabilityExtension],
+        )
+    """
+
+    def __init__(self, *, execution_context: Any = None) -> None:
+        self.execution_context = execution_context
+
+    async def on_operation(self) -> Any:
+        # Note: In Strawberry extensions, `on_operation` is an async generator.
+        # We intercept before the operation runs, yield to allow execution, then clean up.
+
+        op_name = "AnonymousOperation"
+
+        try:
+            if self.execution_context:
+                op_name = self.execution_context.operation_name or op_name
+        except Exception:
+            _LOGGER.debug(
+                "strawberry_extension.parse_failed",
+                exc_info=True,
+                extra={"_skip_enrichers": True},
+            )
+
+        # 1. Update the logging context so StructuredJsonFormatter sees it
+        context = get_user_context() or {}
+        graphql_data = context.get("graphql", {})
+        if isinstance(graphql_data, dict):
+            graphql_data["operation_name"] = op_name
+            context["graphql"] = graphql_data
+            set_user_context(context)
+
+        # 2. Update OpenTelemetry Trace if active
+        try:
+            from opentelemetry import trace as otel_trace  # type: ignore
+
+            span = otel_trace.get_current_span()
+            if span and span.is_recording():
+                span.update_name(f"graphql.operation.{op_name}")
+                span.set_attribute("graphql.operation.name", op_name)
+        except ImportError:
+            pass  # OTel not installed
+        except Exception:
+            _LOGGER.debug(
+                "strawberry_extension.otel_failed",
+                exc_info=True,
+                extra={"_skip_enrichers": True},
+            )
+
+        yield  # Allow Strawberry to execute the actual GraphQL resolvers