021-python-observability 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

{021_python_observability-0.3.0.dist-info → 021_python_observability-0.4.0.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: 021-python-observability
-Version: 0.3.0
+Version: 0.4.0
 Summary: OpenTelemetry metrics, traces and safe JSON logs for FastAPI services
-Project-URL: Repository, https://github.com/from021-io/observability-python
-Project-URL: Changelog, https://github.com/from021-io/observability-python/blob/main/CHANGELOG.md
-Project-URL: Contract, https://github.com/from021-io/observability-python/blob/main/CONTRACT.md
+Project-URL: Repository, https://github.com/from021-io/python-observability
+Project-URL: Changelog, https://github.com/from021-io/python-observability/blob/main/CHANGELOG.md
+Project-URL: Contract, https://github.com/from021-io/python-observability/blob/main/CONTRACT.md
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: asgi,fastapi,observability,opentelemetry,otlp,structlog
@@ -23,9 +23,10 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: fastapi<1,>=0.116
 Requires-Dist: httpx<1,>=0.28
-Requires-Dist: opentelemetry-api<2,>=1.44
-Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.44
-Requires-Dist: opentelemetry-sdk<2,>=1.44
+Requires-Dist: opentelemetry-api<2,>=1.45.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.45.1
+Requires-Dist: opentelemetry-sdk<2,>=1.45.1
+Requires-Dist: requests<3,>=2.34
 Requires-Dist: sqlalchemy[asyncio]<3,>=2.0
 Requires-Dist: structlog<27,>=25.1
 Provides-Extra: prometheus
@@ -34,9 +35,9 @@ Provides-Extra: vercel
 Requires-Dist: vercel<1,>=0.5.8; extra == 'vercel'
 Description-Content-Type: text/markdown
 
-# observability-python
+# python-observability
 
-Repository: `from021-io/observability-python`. Python distribution: `021-python-observability`; import: `observability_021`.
+Repository: `from021-io/python-observability` (named `observability-python` until 2026-10-21; the old URL redirects). Python distribution: `021-python-observability`; import: `observability_021`.
 Tags up to `v0.2.0` use the previous distribution name, `021-observability`.
 
 Common API observability for Python 3.12–3.14: FastAPI request metrics and traces,
@@ -54,14 +55,14 @@ writes [CHANGELOG.md](CHANGELOG.md) and tags `vX.Y.Z`. Consumers depend on a tag
 
 ```toml
 [tool.uv.sources]
-021-python-observability = { git = "https://github.com/from021-io/observability-python.git", tag = "v0.3.0" } # x-release-please-version
+021-python-observability = { git = "https://github.com/from021-io/python-observability.git", tag = "v0.4.0" } # x-release-please-version
 ```
 
 Once releases are published to PyPI, pin the exact version instead; no Git credential is
 needed to install it:
 
 ```sh
-uv add "021-python-observability==0.3.0" # x-release-please-version
+uv add "021-python-observability==0.4.0" # x-release-please-version
 ```
 
 ## Publishing to PyPI
@@ -134,6 +135,14 @@ keep its default value. A different Content-Type does not change the encoding.
 Use custom headers for gateway authentication and verify receipt of both signals
 against the configured gateway during rollout.
 
+`Settings` defaults to no compression. Set `traces_compression` and
+`metrics_compression` to `none`, `gzip` or `deflate` explicitly.
+`Settings.from_env()` reads `OTEL_EXPORTER_OTLP_COMPRESSION` and the signal-specific
+`OTEL_EXPORTER_OTLP_TRACES_COMPRESSION` and `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION`
+overrides. Direct `Settings(...)` calls no longer inherit ambient compression.
+The exporter owns `Content-Encoding` so that the header matches the body. Custom
+and ambient headers cannot override it.
+
 Separate destinations are supported and take precedence over the shared base:
 
 ```dotenv
@@ -225,6 +234,18 @@ Operation/result remain separate dimensions. `operation()` reports `ok`, `error`
 
 ## Logging
 
+Each application lifespan emits an `observability.started` JSON log at INFO with
+`service_name`, `environment`, `service_version` and `observability_version`. The service
+version comes from `OTEL_SERVICE_VERSION`, falling back to `VERCEL_GIT_COMMIT_SHA` and
+then `unknown`; the deployment must set the release version to identify the running
+artifact. The observability version identifies this installed package, not the service.
+The event is suppressed if `LOG_LEVEL` is higher than INFO. Every log handled by this
+package's JSON formatter also includes both version fields, including stdlib and Uvicorn
+logs outside requests. Logging is configured process-wide: for multiple apps in one process,
+request logs use the active app version; logs without request context use the most recently
+configured app version. Logs emitted before setup or through independent handlers are outside
+this formatter's scope.
+
 `get_logger(__name__)` provides structlog logging. Use static event names and approved
 structured fields (`operation`, `op`, `action`, `dependency`, `status`, `reason`, `error_type`). Do not
 interpolate messages or pass business payloads into approved fields. Unknown extra fields

021_python_observability-0.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+observability_021/__init__.py,sha256=0RU4GAtHbN-dyK8tqvEJ9t9e5rxJnRLCUoFN1q7GkuE,283
+observability_021/asgi.py,sha256=M-0s6GjzUvKTSdnAIzQgdZ5l3L531cz2OstTvMfna_U,10800
+observability_021/config.py,sha256=bsZ9noXNtDv52BHlTaOQK14RV0ixh6eGF_xkl009Tq0,5903
+observability_021/dependencies.py,sha256=4PdfFmLHmIBN3IIMHG41d2ify5H7At9wrCkpZvByZRs,6065
+observability_021/logging.py,sha256=Q0lToRDI5lN2cI1lYUwjbtZ7p9aInvzzA7iNtap-dZE,7237
+observability_021/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+observability_021/runtime.py,sha256=9zmrwPvCSjI-OHNXIwn2_rd879WGY078sIpjJoGpN0Y,15873
+021_python_observability-0.4.0.dist-info/METADATA,sha256=8BnQb-KV1Eg2jDvfknWUpefTurD3hjbnUAmINpS4oWc,19266
+021_python_observability-0.4.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+021_python_observability-0.4.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+021_python_observability-0.4.0.dist-info/RECORD,,

{021_python_observability-0.3.0.dist-info → 021_python_observability-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.4
+Generator: hatchling 1.33.0
 Root-Is-Purelib: true
 Tag: py3-none-any

observability_021/asgi.py

@@ -20,6 +20,7 @@ from starlette.responses import JSONResponse
 from .config import Settings, identifier
 from .logging import configure_logging, get_logger
 from .runtime import (
+    INSTRUMENTATION_VERSION,
     BackgroundTask,
     Observability,
     current_observability,
@@ -175,7 +176,11 @@ def setup_observability(
     if app.middleware_stack is not None:
         raise RuntimeError("Configure observability before the application starts")
     settings = settings or Settings.from_env(service_name=service_name)
-    configure_logging(settings.log_level)
+    configure_logging(
+        settings.log_level,
+        service_version=settings.service_version,
+        observability_version=INSTRUMENTATION_VERSION,
+    )
     obs = Observability(
         settings,
         prometheus=prometheus,
@@ -192,9 +197,20 @@ def setup_observability(
     @asynccontextmanager
     async def lifespan(application):
         # Servers accepting an already-built app may configure logging after setup.
-        configure_logging(settings.log_level)
+        configure_logging(
+            settings.log_level,
+            service_version=settings.service_version,
+            observability_version=INSTRUMENTATION_VERSION,
+        )
         token = current_observability.set(obs)
         try:
+            logger.info(
+                "observability.started",
+                service_name=settings.service_name,
+                environment=settings.environment,
+                service_version=settings.service_version,
+                observability_version=INSTRUMENTATION_VERSION,
+            )
             async with original_lifespan(application) as state:
                 yield state
         finally:

observability_021/config.py

@@ -64,6 +64,8 @@ class Settings:
     log_level: str = "INFO"
     serverless: bool = False
     readiness_timeout_seconds: float = 2.0
+    traces_compression: str = "none"
+    metrics_compression: str = "none"
 
     def __post_init__(self) -> None:
         identifier(self.service_name)
@@ -72,6 +74,11 @@ class Settings:
             raise ValueError("service_version must contain 1–128 characters")
         _endpoint(self.traces_endpoint)
         _endpoint(self.metrics_endpoint)
+        if any(
+            value not in {"none", "gzip", "deflate"}
+            for value in (self.traces_compression, self.metrics_compression)
+        ):
+            raise ValueError("OTLP compression must be none, gzip or deflate")
         for value in (
             self.export_timeout_seconds,
             self.metric_interval_ms,
@@ -124,6 +131,14 @@ class Settings:
                     "OTEL_EXPORTER_OTLP_METRICS_HEADERS", env.get("OTEL_EXPORTER_OTLP_HEADERS", "")
                 )
             ),
+            traces_compression=env.get(
+                "OTEL_EXPORTER_OTLP_TRACES_COMPRESSION",
+                env.get("OTEL_EXPORTER_OTLP_COMPRESSION", "none"),
+            ),
+            metrics_compression=env.get(
+                "OTEL_EXPORTER_OTLP_METRICS_COMPRESSION",
+                env.get("OTEL_EXPORTER_OTLP_COMPRESSION", "none"),
+            ),
             export_timeout_seconds=float(env.get("OTEL_EXPORTER_OTLP_TIMEOUT", "2")),
             metric_interval_ms=float(env.get("OTEL_METRIC_EXPORT_INTERVAL", "60000")),
             trace_sample_ratio=float(env.get("OBS_TRACE_SAMPLE_RATIO", "1")),

observability_021/logging.py

@@ -31,6 +31,7 @@ _FIELDS = frozenset(
         "service_name",
         "environment",
         "service_version",
+        "observability_version",
         "request_id",
         "trace_id",
         "span_id",
@@ -154,9 +155,21 @@ def _sanitize(_logger, _method, event):
     return result
 
 
-def configure_logging(level: str = "INFO") -> None:
+def configure_logging(
+    level: str = "INFO",
+    *,
+    service_version: str = "unknown",
+    observability_version: str = "unknown",
+) -> None:
+    def add_versions(_logger, _method, event):
+        context = structlog.contextvars.get_contextvars()
+        event["service_version"] = context.get("service_version", service_version)
+        event["observability_version"] = observability_version
+        return event
+
     shared = [
         structlog.contextvars.merge_contextvars,
+        add_versions,
         structlog.stdlib.add_log_level,
         structlog.stdlib.add_logger_name,
         structlog.processors.TimeStamper(fmt="iso", utc=True, key="timestamp"),
@@ -174,7 +187,7 @@ def configure_logging(level: str = "INFO") -> None:
     handler = logging.StreamHandler(sys.stdout)
     handler.setFormatter(
         structlog.stdlib.ProcessorFormatter(
-            processors=[_sanitize, structlog.processors.JSONRenderer(sort_keys=True)],
+            processors=[add_versions, _sanitize, structlog.processors.JSONRenderer(sort_keys=True)],
             foreign_pre_chain=[*shared, structlog.stdlib.ExtraAdder(allow=_FIELDS)],
         )
     )

observability_021/runtime.py

@@ -17,6 +17,7 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     import httpx
 
+from opentelemetry.exporter.otlp.proto.http import Compression
 from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 from opentelemetry.metrics import Observation
@@ -27,12 +28,14 @@ from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
+from requests import PreparedRequest, Request, Session
+from requests.structures import CaseInsensitiveDict
 
 from .config import Settings, identifier
 from .logging import get_logger
 
 # The package version, kept in step by release-please.
-INSTRUMENTATION_VERSION = "0.3.0"  # x-release-please-version
+INSTRUMENTATION_VERSION = "0.4.0"  # x-release-please-version
 
 # Seconds, with finite boundaries for both ordinary API traffic and long ingestion.
 DURATION_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300)
@@ -53,6 +56,25 @@ def error_kind(error: BaseException) -> str:
     return "internal_error"
 
 
+class _ExportSession(Session):
+    def __init__(self, headers: Mapping[str, str], compression: Compression):
+        super().__init__()
+        self._export_headers = CaseInsensitiveDict(
+            {"Content-Type": "application/x-protobuf", **headers}
+        )
+        self._export_headers.pop("Content-Encoding", None)
+        if compression is not Compression.NoCompression:
+            self._export_headers["Content-Encoding"] = compression.value
+
+    def prepare_request(self, request: Request) -> PreparedRequest:
+        request.headers = CaseInsensitiveDict(self._export_headers)
+        prepared = super().prepare_request(request)
+        # Requests can add netrc credentials during preparation.
+        prepared.headers.pop("Authorization", None)
+        prepared.headers.update(self._export_headers)
+        return prepared
+
+
 class Observability:
     def __init__(
         self,
@@ -82,13 +104,15 @@ class Observability:
             sampler=ParentBased(TraceIdRatioBased(settings.trace_sample_ratio)),
             shutdown_on_exit=False,
         )
-        # A nonempty explicit mapping prevents SDK fallback to ambient OTLP credentials.
-        # Content-Type is already required by OTLP/HTTP, so no extra header is introduced.
         if settings.traces_endpoint:
             self.tracer_provider.add_span_processor(
                 BatchSpanProcessor(
                     OTLPSpanExporter(
                         endpoint=settings.traces_endpoint,
+                        session=_ExportSession(
+                            settings.traces_headers, Compression(settings.traces_compression)
+                        ),
+                        compression=Compression(settings.traces_compression),
                         headers={
                             "Content-Type": "application/x-protobuf",
                             **settings.traces_headers,
@@ -110,6 +134,10 @@ class Observability:
                 PeriodicExportingMetricReader(
                     OTLPMetricExporter(
                         endpoint=settings.metrics_endpoint,
+                        session=_ExportSession(
+                            settings.metrics_headers, Compression(settings.metrics_compression)
+                        ),
+                        compression=Compression(settings.metrics_compression),
                         headers={
                             "Content-Type": "application/x-protobuf",
                             **settings.metrics_headers,

021_python_observability-0.3.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-observability_021/__init__.py,sha256=0RU4GAtHbN-dyK8tqvEJ9t9e5rxJnRLCUoFN1q7GkuE,283
-observability_021/asgi.py,sha256=2cpHSdmrNindHIY_dYdMwhBXGhefJlCL8VfSEkf4Zb4,10212
-observability_021/config.py,sha256=4LR6nNNdD2-2pso-Z4NRbLwsgiXKa8T4D-8X1bbAcNg,5232
-observability_021/dependencies.py,sha256=4PdfFmLHmIBN3IIMHG41d2ify5H7At9wrCkpZvByZRs,6065
-observability_021/logging.py,sha256=OjJIRKmJJ4-RGafyvHaYKUjKInjscOIHhn5Ficx70Oc,6799
-observability_021/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-observability_021/runtime.py,sha256=DfaQPn5ZbAjAaJ-IYu_RCijnxOqBMDPEgssrdvwTTGc,14547
-021_python_observability-0.3.0.dist-info/METADATA,sha256=BzXNnBB6so7eNlsGsH30nW6AiOJRXrYnc-XxTck5xLE,17743
-021_python_observability-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-021_python_observability-0.3.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-021_python_observability-0.3.0.dist-info/RECORD,,