policyengine-observability 0.2.0__py3-none-any.whl

policyengine_observability/config.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+DEFAULT_METRIC_ATTRIBUTE_KEYS = (
+    "service.name",
+    "service.role",
+    "deployment.environment",
+    "operation",
+    "flavor",
+    "route",
+    "method",
+    "endpoint",
+    "status_code",
+    "country_id",
+    "backend",
+    "requested_version",
+    "resolved_channel",
+    "auth_result",
+    "segment",
+    "event",
+    "error_type",
+    "model",
+    "tool",
+    "stop_reason",
+    "iteration",
+    "provider",
+)
+
+
+def bool_from_env(name: str, default: bool) -> bool:
+    raw_value = os.getenv(name)
+    if raw_value is None:
+        return default
+    return raw_value.strip().lower() not in {"0", "false", "no", "off"}
+
+
+def csv_from_env(name: str) -> tuple[str, ...]:
+    raw_value = os.getenv(name)
+    if raw_value is None:
+        return ()
+    return tuple(part.strip() for part in raw_value.split(",") if part.strip())
+
+
+def float_from_env(name: str, default: float) -> float:
+    raw_value = os.getenv(name)
+    if raw_value is None:
+        return default
+    try:
+        return float(raw_value)
+    except ValueError:
+        return default
+
+
+def default_environment() -> str:
+    return (
+        os.getenv("OBSERVABILITY_ENVIRONMENT")
+        or os.getenv("DEPLOYMENT_ENVIRONMENT")
+        or os.getenv("APP_ENV")
+        or os.getenv("ENVIRONMENT")
+        or "development"
+    )
+
+
+@dataclass(frozen=True)
+class ObservabilityConfig:
+    service_name: str = "policyengine-service"
+    service_role: str = "api"
+    environment: str = "development"
+    enabled: bool = True
+    request_logs_enabled: bool = True
+    log_raw_ip: bool = True
+    log_level: int = logging.INFO
+    otel_enabled: bool = False
+    otlp_endpoint: str | None = None
+    otlp_protocol: str = "grpc"
+    span_prefix: str | None = None
+    tracer_name: str | None = None
+    meter_name: str | None = None
+    shutdown_timeout_seconds: float = 3.0
+    instrument_fastapi: bool = False
+    instrument_httpx: bool = False
+    metric_attribute_keys: tuple[str, ...] = DEFAULT_METRIC_ATTRIBUTE_KEYS
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        service_name: str,
+        service_role: str = "api",
+        enabled_default: bool = True,
+        otel_enabled_default: bool = False,
+        span_prefix: str | None = None,
+        instrument_fastapi: bool = False,
+        instrument_httpx: bool = False,
+        metric_attribute_keys: Sequence[str] | None = None,
+        extra_metric_attribute_keys: Sequence[str] = (),
+    ) -> ObservabilityConfig:
+        level_name = os.getenv("OBSERVABILITY_LOG_LEVEL", "INFO").upper()
+        log_level = getattr(logging, level_name, logging.INFO)
+        otlp_protocol = (
+            os.getenv("OTEL_EXPORTER_OTLP_PROTOCOL")
+            or os.getenv("OBSERVABILITY_OTLP_PROTOCOL")
+            or cls.otlp_protocol
+        )
+        env_metric_keys = csv_from_env("OBSERVABILITY_METRIC_ATTRIBUTE_KEYS")
+        env_extra_metric_keys = csv_from_env(
+            "OBSERVABILITY_EXTRA_METRIC_ATTRIBUTE_KEYS"
+        )
+        resolved_metric_keys = _dedupe(
+            env_metric_keys
+            or metric_attribute_keys
+            or DEFAULT_METRIC_ATTRIBUTE_KEYS,
+            (*extra_metric_attribute_keys, *env_extra_metric_keys),
+        )
+        return cls(
+            service_name=os.getenv("OBSERVABILITY_SERVICE_NAME")
+            or os.getenv("OTEL_SERVICE_NAME")
+            or service_name,
+            service_role=service_role,
+            environment=default_environment(),
+            enabled=bool_from_env("OBSERVABILITY_ENABLED", enabled_default),
+            request_logs_enabled=bool_from_env(
+                "OBSERVABILITY_REQUEST_LOGS_ENABLED",
+                True,
+            ),
+            log_raw_ip=bool_from_env("OBSERVABILITY_LOG_RAW_IP", True),
+            log_level=log_level,
+            otel_enabled=bool_from_env(
+                "OTEL_ENABLED",
+                bool_from_env(
+                    "OBSERVABILITY_OTEL_ENABLED",
+                    otel_enabled_default,
+                ),
+            ),
+            otlp_endpoint=os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT") or None,
+            otlp_protocol=otlp_protocol,
+            span_prefix=span_prefix,
+            tracer_name=os.getenv("OBSERVABILITY_TRACER_NAME"),
+            meter_name=os.getenv("OBSERVABILITY_METER_NAME"),
+            shutdown_timeout_seconds=float_from_env(
+                "OBSERVABILITY_SHUTDOWN_TIMEOUT_SECONDS",
+                3.0,
+            ),
+            instrument_fastapi=bool_from_env(
+                "OBSERVABILITY_INSTRUMENT_FASTAPI",
+                instrument_fastapi,
+            ),
+            instrument_httpx=bool_from_env(
+                "OBSERVABILITY_INSTRUMENT_HTTPX",
+                instrument_httpx,
+            ),
+            metric_attribute_keys=resolved_metric_keys,
+        )
+
+
+def _dedupe(
+    base: Sequence[str],
+    extra: Sequence[str] = (),
+) -> tuple[str, ...]:
+    return tuple(dict.fromkeys((*base, *extra)))

policyengine_observability/context.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from .config import ObservabilityConfig
+
+
+@dataclass
+class ErrorRecord:
+    type: str
+    message: str
+    handled: bool
+    stack: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.type,
+            "message": self.message,
+            "handled": self.handled,
+            "stack": self.stack,
+        }
+
+
+@dataclass
+class OperationObservabilityContext:
+    config: ObservabilityConfig
+    name: str
+    flavor: str | None = None
+    attributes: dict[str, Any] = field(default_factory=dict)
+    timings_ms: dict[str, float] = field(default_factory=dict)
+    emit_log: bool = True
+    record_metric: bool = True
+    started_at: float = field(default_factory=time.perf_counter)
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    error: ErrorRecord | None = None
+    emitted: bool = False
+    metric_recorded: bool = False
+    span_handle: Any = None
+    context_token: Any = None
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        if value is None:
+            return
+        if hasattr(value, "value"):
+            value = value.value
+        self.attributes[key] = value
+
+    def duration_seconds(self) -> float:
+        return time.perf_counter() - self.started_at
+
+    def metric_attributes(self, **extra: Any) -> dict[str, str]:
+        attrs: dict[str, Any] = {
+            "service.name": self.config.service_name,
+            "service.role": self.config.service_role,
+            "deployment.environment": self.config.environment,
+            "operation": self.name,
+            "flavor": self.flavor,
+        }
+        for key in self.config.metric_attribute_keys:
+            if key in self.attributes:
+                attrs[key] = self.attributes[key]
+        attrs.update(extra)
+        return _metric_attrs(attrs, self.config.metric_attribute_keys)
+
+    def span_attributes(self, **extra: Any) -> dict[str, Any]:
+        attrs: dict[str, Any] = {
+            "service.name": self.config.service_name,
+            "service.role": self.config.service_role,
+            "deployment.environment": self.config.environment,
+            "policyengine.operation": self.name,
+            "policyengine.flavor": self.flavor,
+        }
+        attrs.update(
+            {
+                f"policyengine.{key}": value
+                for key, value in self.attributes.items()
+                if value is not None
+            }
+        )
+        attrs.update(extra)
+        return {
+            key: value for key, value in attrs.items() if value is not None
+        }
+
+    def as_log_record(
+        self,
+        *,
+        trace_id: str | None,
+        span_id: str | None,
+    ) -> dict[str, Any]:
+        event = "operation_failed" if self.error else "operation_completed"
+        return {
+            "schema_version": "policyengine.observability.operation.v1",
+            "event": event,
+            "service_name": self.config.service_name,
+            "service_role": self.config.service_role,
+            "environment": self.config.environment,
+            "created_at": self.created_at.isoformat(),
+            "operation": self.name,
+            "flavor": self.flavor,
+            "trace_id": trace_id,
+            "span_id": span_id,
+            "duration_ms": round(self.duration_seconds() * 1000, 3),
+            "timings_ms": dict(self.timings_ms),
+            **self.attributes,
+            "error": self.error.as_dict() if self.error else None,
+        }
+
+
+@dataclass
+class RequestObservabilityContext:
+    config: ObservabilityConfig
+    request_id: str
+    method: str
+    route: str
+    path: str
+    endpoint: str | None
+    query_keys: list[str]
+    content_length_bytes: int | None
+    inbound: dict[str, Any]
+    internal_dispatch: bool = False
+    started_at: float = field(default_factory=time.perf_counter)
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    attributes: dict[str, Any] = field(default_factory=dict)
+    timings_ms: dict[str, float] = field(default_factory=dict)
+    status_code: int | None = None
+    error: ErrorRecord | None = None
+    emitted: bool = False
+    request_metric_recorded: bool = False
+    active_closed: bool = False
+    span_closed: bool = False
+    server_span_cm: Any = None
+    server_span: Any = None
+    context_token: Any = None
+    operation_context: OperationObservabilityContext | None = None
+    operation_token: Any = None
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        if value is None:
+            return
+        if hasattr(value, "value"):
+            value = value.value
+        self.attributes[key] = value
+
+    def duration_seconds(self) -> float:
+        return time.perf_counter() - self.started_at
+
+    def metric_attributes(self, **extra: Any) -> dict[str, str]:
+        attrs: dict[str, Any] = {
+            "service.name": self.config.service_name,
+            "service.role": self.config.service_role,
+            "deployment.environment": self.config.environment,
+            "route": self.route,
+            "method": self.method,
+            "endpoint": self.endpoint,
+        }
+        if self.status_code is not None:
+            attrs["status_code"] = str(self.status_code)
+        for key in self.config.metric_attribute_keys:
+            if key in self.attributes:
+                attrs[key] = self.attributes[key]
+        attrs.update(extra)
+        return _metric_attrs(attrs, self.config.metric_attribute_keys)
+
+    def span_attributes(self, **extra: Any) -> dict[str, Any]:
+        attrs: dict[str, Any] = {
+            "service.name": self.config.service_name,
+            "service.role": self.config.service_role,
+            "deployment.environment": self.config.environment,
+            "http.request.method": self.method,
+            "http.route": self.route,
+            "url.path": self.path,
+            "policyengine.endpoint": self.endpoint,
+            "policyengine.request_id": self.request_id,
+        }
+        if self.status_code is not None:
+            attrs["http.response.status_code"] = self.status_code
+        for key in (
+            "country_id",
+            "backend",
+            "requested_version",
+            "resolved_channel",
+            "auth_result",
+        ):
+            if key in self.attributes:
+                attrs[f"policyengine.{key}"] = self.attributes[key]
+        attrs.update(extra)
+        return {
+            key: value for key, value in attrs.items() if value is not None
+        }
+
+    def as_log_record(
+        self,
+        *,
+        trace_id: str | None,
+        span_id: str | None,
+    ) -> dict[str, Any]:
+        event = (
+            "http_request_failed" if self.error else "http_request_completed"
+        )
+        status_code = self.status_code or (500 if self.error else None)
+        return {
+            "schema_version": "policyengine.observability.request.v1",
+            "event": event,
+            "service_name": self.config.service_name,
+            "service_role": self.config.service_role,
+            "environment": self.config.environment,
+            "created_at": self.created_at.isoformat(),
+            "request_id": self.request_id,
+            "trace_id": trace_id,
+            "span_id": span_id,
+            "method": self.method,
+            "route": self.route,
+            "path": self.path,
+            "query_keys": self.query_keys,
+            "endpoint": self.endpoint,
+            "status_code": status_code,
+            "duration_ms": round(self.duration_seconds() * 1000, 3),
+            **self.inbound,
+            "timings_ms": dict(self.timings_ms),
+            **self.attributes,
+            "error": self.error.as_dict() if self.error else None,
+        }
+
+
+def _metric_attrs(
+    attrs: dict[str, Any],
+    metric_attribute_keys: tuple[str, ...],
+) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for key in metric_attribute_keys:
+        value = attrs.get(key)
+        if value is not None:
+            result[key] = str(value)
+    return result

policyengine_observability/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional instrumentation integrations."""

policyengine_observability/integrations/httpx.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from ..runtime import ObservabilityRuntime, observability_runtime
+
+
+def instrument_httpx(runtime: ObservabilityRuntime | None = None) -> None:
+    runtime = runtime or observability_runtime()
+    runtime.instrument_httpx()

policyengine_observability/logging.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import logging
+
+
+class PlainMessageFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        return record.getMessage()
+
+
+def configure_plain_logger(logger: logging.Logger, level: int) -> None:
+    logger.setLevel(level)
+    logger.propagate = False
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(PlainMessageFormatter())
+        logger.addHandler(handler)