obsforge 0.1.1__py3-none-any.whl

obsforge/__init__.py

@@ -0,0 +1,44 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from obsforge.api.context import ContextManager
+from obsforge.api.decorators import instrument
+from obsforge.api.events import EventClient
+from obsforge.api.logger import Logger
+from obsforge.config.bootstrap import BootstrapResult, bootstrap
+from obsforge.config.settings import ObsforgeSettings
+from obsforge.core.models import CanonicalEvent, Event, EventKind, Outcome, Severity
+from obsforge.instrumentation.db.engine import DBObservabilityEngine
+from obsforge.instrumentation.exceptions.engine import ExceptionIntelligenceEngine
+from obsforge.instrumentation.http.engine import APIRuntimeEngine
+from obsforge.integrations.logging_bridge import (
+    ObsforgeLoggingHandler,
+    install_logging_bridge,
+)
+from obsforge.propagation.distributed import DistributedCorrelationEngine
+
+try:
+    __version__ = version("obsforge")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "APIRuntimeEngine",
+    "BootstrapResult",
+    "CanonicalEvent",
+    "ContextManager",
+    "DBObservabilityEngine",
+    "DistributedCorrelationEngine",
+    "Event",
+    "EventClient",
+    "EventKind",
+    "ExceptionIntelligenceEngine",
+    "Logger",
+    "ObsforgeLoggingHandler",
+    "ObsforgeSettings",
+    "Outcome",
+    "Severity",
+    "__version__",
+    "bootstrap",
+    "install_logging_bridge",
+    "instrument",
+]

obsforge/api/__init__.py

@@ -0,0 +1,5 @@
+from obsforge.api.context import ContextManager
+from obsforge.api.events import EventClient
+from obsforge.api.logger import Logger
+
+__all__ = ["ContextManager", "EventClient", "Logger"]

obsforge/api/context.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from obsforge.core.models import CorrelationContext, TraceContext
+from obsforge.propagation.correlation import CorrelationManager
+
+
+class ContextManager:
+    """Public facade for request-local observability context."""
+
+    def __init__(self, manager: CorrelationManager | None = None) -> None:
+        self._manager = manager or CorrelationManager()
+
+    def get_correlation(self) -> CorrelationContext | None:
+        return self._manager.get_correlation()
+
+    def set_correlation(self, context: CorrelationContext) -> None:
+        self._manager.set_correlation(context)
+
+    def clear_correlation(self) -> None:
+        self._manager.clear()
+
+    def get_trace(self) -> TraceContext | None:
+        return self._manager.get_trace()
+
+    def set_trace(self, context: TraceContext) -> None:
+        self._manager.set_trace(context)
+
+    def bind_attributes(self, attributes: Mapping[str, Any]) -> None:
+        self._manager.bind_attributes(attributes)

obsforge/api/decorators.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from obsforge.api.events import EventClient
+
+
+def instrument(event_client: EventClient, event_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Attach semantic lifecycle events around a sync or async function."""
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        if inspect.iscoroutinefunction(func):
+            @wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                await event_client.emit_named(event_name=f"{event_name}.started")
+                try:
+                    result = await func(*args, **kwargs)
+                except Exception:
+                    await event_client.emit_named(event_name=f"{event_name}.failed")
+                    raise
+                await event_client.emit_named(event_name=f"{event_name}.succeeded")
+                return result
+
+            return async_wrapper
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            event_client.emit_named_sync(event_name=f"{event_name}.started")
+            try:
+                result = func(*args, **kwargs)
+            except Exception:
+                event_client.emit_named_sync(event_name=f"{event_name}.failed")
+                raise
+            event_client.emit_named_sync(event_name=f"{event_name}.succeeded")
+            return result
+
+        return sync_wrapper
+
+    return decorator

obsforge/api/events.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from obsforge.core.models import Event
+from obsforge.runtime.pipeline import EventPipeline
+
+
+class EventClient:
+    """Public API for semantic event emission."""
+
+    def __init__(self, pipeline: EventPipeline) -> None:
+        self._pipeline = pipeline
+
+    async def emit(self, event: Event) -> None:
+        await self._pipeline.process(event)
+
+    def emit_sync(self, event: Event) -> None:
+        self._pipeline.process_sync(event)
+
+    async def emit_named(self, event_name: str, **context: Any) -> None:
+        await self.emit(Event.named(event_name=event_name, context=context))
+
+    def emit_named_sync(self, event_name: str, **context: Any) -> None:
+        self.emit_sync(Event.named(event_name=event_name, context=context))

obsforge/api/logger.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+from obsforge.api.events import EventClient
+from obsforge.core.models import Event, Severity
+
+
+class Logger:
+    """High-level logger that always writes semantic events."""
+
+    def __init__(self, event_client: EventClient) -> None:
+        self._event_client = event_client
+
+    async def log(
+        self,
+        event_name: str,
+        *,
+        severity: Severity = Severity.INFO,
+        message: str | None = None,
+        **context: Any,
+    ) -> None:
+        event = Event.named(
+            event_name=event_name,
+            severity=severity,
+            message=message,
+            context=context,
+        )
+        await self._event_client.emit(event)
+
+    def log_sync(
+        self,
+        event_name: str,
+        *,
+        severity: Severity = Severity.INFO,
+        message: str | None = None,
+        **context: Any,
+    ) -> None:
+        event = Event.named(
+            event_name=event_name,
+            severity=severity,
+            message=message,
+            context=context,
+        )
+        self._event_client.emit_sync(event)

obsforge/config/__init__.py

@@ -0,0 +1,4 @@
+from obsforge.config.bootstrap import bootstrap
+from obsforge.config.settings import ObsforgeSettings
+
+__all__ = ["ObsforgeSettings", "bootstrap"]

obsforge/config/bootstrap.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from typing import Any
+
+from obsforge.api.context import ContextManager
+from obsforge.api.events import EventClient
+from obsforge.api.logger import Logger
+from obsforge.config.settings import ObsforgeSettings
+from obsforge.config.state import set_default_event_client
+from obsforge.core.contracts import EventProcessor, TelemetryExporter
+from obsforge.core.errors import ConfigurationError
+from obsforge.core.taxonomy import TaxonomyPolicy
+from obsforge.encoding.json import OrjsonEventEncoder
+from obsforge.instrumentation.db.engine import DBObservabilityEngine
+from obsforge.instrumentation.db.state import set_default_db_engine
+from obsforge.instrumentation.exceptions.engine import ExceptionIntelligenceEngine
+from obsforge.instrumentation.exceptions.state import set_default_exception_engine
+from obsforge.instrumentation.http.engine import APIRuntimeEngine
+from obsforge.instrumentation.http.state import set_default_api_engine
+from obsforge.plugins.builtin import DefaultTaxonomyPlugin
+from obsforge.plugins.manager import PluginManager
+from obsforge.plugins.registry import DefaultPluginRegistry
+from obsforge.propagation.correlation import CorrelationManager
+from obsforge.propagation.distributed import DistributedCorrelationEngine
+from obsforge.propagation.state import set_default_distributed_engine
+from obsforge.runtime.pii import PIIScrubber
+from obsforge.runtime.pipeline import EventPipeline
+from obsforge.runtime.policies.loki_policy import (
+    LokiLabelPolicy,
+    LokiSerializer,
+    StructuredMetadataPolicy,
+)
+from obsforge.runtime.processors import (
+    CorrelationProcessor,
+    RuntimeContextProcessor,
+    TaxonomyProcessor,
+    TimestampProcessor,
+)
+from obsforge.runtime.redaction import RedactionProcessor
+from obsforge.runtime.sampling import SeveritySamplingPolicy
+from obsforge.transport.stdout import StdoutSink
+
+# NOTE: ``obsforge.telemetry.otel_logs`` is imported lazily inside bootstrap()
+# only when OTel is enabled, so a plain ``import obsforge`` never touches the
+# optional opentelemetry import graph.
+
+
+class BootstrapResult:
+    def __init__(
+        self,
+        *,
+        logger: Logger,
+        event_client: EventClient,
+        context_manager: ContextManager,
+        pipeline: EventPipeline,
+        plugin_manager: PluginManager,
+        distributed_engine: DistributedCorrelationEngine,
+        api_engine: APIRuntimeEngine,
+        db_engine: DBObservabilityEngine,
+        exception_engine: ExceptionIntelligenceEngine,
+    ) -> None:
+        self.logger = logger
+        self.event_client = event_client
+        self.context_manager = context_manager
+        self.pipeline = pipeline
+        self.plugin_manager = plugin_manager
+        self.distributed_engine = distributed_engine
+        self.api_engine = api_engine
+        self.db_engine = db_engine
+        self.exception_engine = exception_engine
+
+
+def bootstrap(
+    settings: ObsforgeSettings | None = None,
+    *,
+    otel_logger_provider: Any | None = None,
+    otel_tracer_provider: Any | None = None,
+) -> BootstrapResult:
+    """Initialize the SDK.
+
+    To make OTel export actually emit, opt in via settings AND inject a configured
+    provider here: ``otel.logs_enabled=True`` needs ``otel_logger_provider=...`` and
+    ``otel.traces_enabled=True`` needs ``otel_tracer_provider=...``. Enabling export
+    without a usable provider raises ``ConfigurationError`` rather than silently
+    dropping every record.
+    """
+    settings = settings or ObsforgeSettings()
+    correlation_manager = CorrelationManager()
+    registry = DefaultPluginRegistry()
+    DefaultTaxonomyPlugin().setup(registry)
+    plugin_manager = PluginManager(registry=registry)
+    plugin_manager.load_entry_points()
+
+    processors: list[EventProcessor] = [
+        TimestampProcessor(),
+        RuntimeContextProcessor(settings),
+        TaxonomyProcessor(TaxonomyPolicy(reserved_namespaces=registry.namespaces())),
+        CorrelationProcessor(correlation_manager),
+        RedactionProcessor(
+            settings.redact_keys,
+            scrubber=PIIScrubber(enabled=settings.security.scrub_pii),
+        ),
+        *registry.processors(),
+    ]
+
+    serializer = LokiSerializer(
+        label_policy=LokiLabelPolicy.preset(settings.loki.preset),
+        metadata_policy=StructuredMetadataPolicy(),
+    )
+
+    exporters: list[TelemetryExporter] = list(registry.exporters())
+    if settings.otel.logs_enabled:
+        from obsforge.telemetry.otel_logs import OTelLogExporter
+
+        log_exporter = OTelLogExporter(
+            logger_provider=otel_logger_provider,
+            logger_name=settings.otel.logger_name,
+        )
+        if not log_exporter.enabled:
+            raise ConfigurationError(
+                "otel.logs_enabled=True but no usable OpenTelemetry LoggerProvider was "
+                "provided. Pass a configured provider: "
+                "bootstrap(settings, otel_logger_provider=provider)."
+            )
+        exporters.append(log_exporter)
+    if settings.otel.traces_enabled:
+        from obsforge.telemetry.otel_traces import OTelTraceBridge
+
+        trace_bridge = OTelTraceBridge(
+            tracer_provider=otel_tracer_provider,
+            tracer_name=settings.otel.tracer_name,
+        )
+        if not trace_bridge.enabled:
+            raise ConfigurationError(
+                "otel.traces_enabled=True but no usable OpenTelemetry TracerProvider was "
+                "provided. Pass a configured provider: "
+                "bootstrap(settings, otel_tracer_provider=provider)."
+            )
+        exporters.append(trace_bridge)
+
+    pipeline = EventPipeline(
+        processors=processors,
+        encoder=OrjsonEventEncoder(serializer),
+        sinks=[StdoutSink(), *registry.sinks()],
+        exporters=exporters,
+        sampling=SeveritySamplingPolicy(min_severity=settings.min_severity),
+    )
+
+    event_client = EventClient(pipeline)
+    set_default_event_client(event_client)
+    logger = Logger(event_client)
+    context_manager = ContextManager(correlation_manager)
+    distributed_engine = DistributedCorrelationEngine(
+        correlation_manager=correlation_manager,
+        settings=settings,
+    )
+    set_default_distributed_engine(distributed_engine)
+    exception_engine = ExceptionIntelligenceEngine(
+        event_client=event_client,
+        correlation_manager=correlation_manager,
+        settings=settings,
+    )
+    set_default_exception_engine(exception_engine)
+    db_engine = DBObservabilityEngine(
+        event_client=event_client,
+        correlation_manager=correlation_manager,
+        settings=settings,
+        exception_engine=exception_engine,
+    )
+    set_default_db_engine(db_engine)
+    api_engine = APIRuntimeEngine(
+        event_client=event_client,
+        correlation_manager=correlation_manager,
+        settings=settings,
+        exception_engine=exception_engine,
+        distributed_engine=distributed_engine,
+    )
+    set_default_api_engine(api_engine)
+
+    return BootstrapResult(
+        logger=logger,
+        event_client=event_client,
+        context_manager=context_manager,
+        pipeline=pipeline,
+        plugin_manager=plugin_manager,
+        distributed_engine=distributed_engine,
+        api_engine=api_engine,
+        db_engine=db_engine,
+        exception_engine=exception_engine,
+    )

obsforge/config/settings.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import os
+import platform
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from obsforge.core.models import Severity
+
+
+def _default_service_name() -> str:
+    """Honor the OpenTelemetry-standard ``OTEL_SERVICE_NAME`` env var so logs are
+    attributable out of the box; fall back to a clearly-unset sentinel."""
+    env = os.environ.get("OTEL_SERVICE_NAME", "").strip()
+    return env or "unknown-service"
+
+
+class HTTPInstrumentationSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    header_allowlist: set[str] = Field(
+        default_factory=lambda: {
+            "accept",
+            "content-type",
+            "content-length",
+            "user-agent",
+            "x-request-id",
+            "x-correlation-id",
+        }
+    )
+    header_redactlist: set[str] = Field(
+        default_factory=lambda: {
+            "authorization",
+            "cookie",
+            "set-cookie",
+            "proxy-authorization",
+            "x-api-key",
+            "x-auth-token",
+        }
+    )
+    payload_preview_bytes: int = 256
+    payload_capture_bytes: int = 4096
+    slow_request_threshold_ms: float = 500.0
+    anomaly_window_size: int = 50
+    anomaly_min_samples: int = 10
+    retry_storm_threshold: int = 3
+    saturation_latency_threshold_ms: float = 1000.0
+    saturation_failure_ratio: float = 0.3
+
+
+class ExceptionInstrumentationSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    max_frames: int = 50
+    max_locals_per_frame: int = 12
+    max_local_preview_chars: int = 160
+    max_cause_depth: int = 8
+    dedupe_window_seconds: int = 900
+    sensitive_local_names: set[str] = Field(
+        default_factory=lambda: {
+            "password",
+            "passwd",
+            "secret",
+            "token",
+            "api_key",
+            "authorization",
+            "cookie",
+            "session",
+        }
+    )
+
+
+class DatabaseInstrumentationSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    slow_query_threshold_ms: float = 250.0
+    saturation_latency_threshold_ms: float = 1000.0
+    pool_exhaustion_waiters_threshold: int = 1
+    leak_checkout_threshold_ms: float = 30000.0
+    retry_storm_threshold: int = 3
+    max_query_preview_chars: int = 240
+    max_normalized_query_chars: int = 2000
+    query_sample_rate: float = 1.0
+    redacted_literals_placeholder: str = "?"
+
+
+class DistributedCorrelationSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    correlation_header: str = "x-correlation-id"
+    request_header: str = "x-request-id"
+    tenant_header: str = "x-tenant-id"
+    user_header: str = "x-user-id"
+    operation_header: str = "x-operation-id"
+    transaction_header: str = "x-transaction-id"
+    celery_header_prefix: str = "obsforge."
+    kafka_header_prefix: str = "obsforge."
+    rabbitmq_header_prefix: str = "obsforge."
+    baggage_keys: tuple[str, ...] = (
+        "tenant_id",
+        "user_id",
+        "operation_id",
+        "transaction_id",
+        "correlation_id",
+    )
+
+
+class SecuritySettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    scrub_pii: bool = True
+    trust_inbound_identity: bool = True
+    max_identifier_chars: int = 256
+    max_baggage_items: int = 32
+    max_baggage_value_chars: int = 1024
+
+
+class LokiSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    preset: Literal["dev", "staging", "prod"] = "prod"
+
+
+class OTelSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    logs_enabled: bool = False
+    traces_enabled: bool = False
+    logger_name: str = "obsforge"
+    tracer_name: str = "obsforge"
+
+
+class ObsforgeSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    service_name: str = Field(default_factory=_default_service_name)
+    service_version: str = "0.1.0"
+    environment: str = "development"
+    namespace: str = "application"
+    deployment_ring: str | None = None
+    runtime_version: str = platform.python_version()
+    process_pid: int = os.getpid()
+    host_name: str | None = platform.node() or None
+    cloud_provider: str | None = None
+    cloud_region: str | None = None
+    k8s_cluster_name: str | None = None
+    k8s_namespace_name: str | None = None
+    k8s_deployment_name: str | None = None
+    telemetry_sdk_version: str = "0.1.1"
+    min_severity: Severity = Severity.INFO
+    redact_keys: set[str] = Field(
+        default_factory=lambda: {
+            "password",
+            "passwd",
+            "token",
+            "secret",
+            "api_key",
+            "apikey",
+            "authorization",
+            "auth",
+            "cookie",
+            "session",
+            "credit_card",
+            "card_number",
+            "ssn",
+            "private_key",
+        }
+    )
+    loki: LokiSettings = Field(default_factory=LokiSettings)
+    otel: OTelSettings = Field(default_factory=OTelSettings)
+    security: SecuritySettings = Field(default_factory=SecuritySettings)
+    http: HTTPInstrumentationSettings = Field(default_factory=HTTPInstrumentationSettings)
+    exceptions: ExceptionInstrumentationSettings = Field(default_factory=ExceptionInstrumentationSettings)
+    database: DatabaseInstrumentationSettings = Field(default_factory=DatabaseInstrumentationSettings)
+    distributed: DistributedCorrelationSettings = Field(default_factory=DistributedCorrelationSettings)

obsforge/config/state.py

@@ -0,0 +1,53 @@
+"""Process-wide default :class:`EventClient`.
+
+The default is registered by :func:`obsforge.bootstrap` and lets zero-config
+entry points (notably :func:`install_logging_bridge`) work as a true one-liner:
+when no client is passed, the last bootstrapped one is reused, or a default SDK
+is initialized on the spot.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from obsforge.api.events import EventClient
+
+_default_event_client: EventClient | None = None
+# Reentrant: get_or_bootstrap_event_client() holds the lock while calling
+# bootstrap(), which re-enters via set_default_event_client().
+_lock = threading.RLock()
+
+
+def set_default_event_client(client: EventClient) -> None:
+    global _default_event_client
+    with _lock:
+        _default_event_client = client
+
+
+def get_default_event_client() -> EventClient | None:
+    return _default_event_client
+
+
+def reset_default_event_client() -> None:
+    global _default_event_client
+    with _lock:
+        _default_event_client = None
+
+
+def get_or_bootstrap_event_client() -> EventClient:
+    """Return the process-default client, bootstrapping a default SDK if none.
+
+    Thread-safe: the bootstrap-if-absent path uses double-checked locking so
+    concurrent first-time callers initialize exactly one default SDK."""
+    client = _default_event_client
+    if client is not None:
+        return client
+    with _lock:
+        if _default_event_client is not None:
+            return _default_event_client
+        from obsforge.config.bootstrap import bootstrap
+
+        # bootstrap() registers itself as the default via set_default_event_client().
+        return bootstrap().event_client

obsforge/core/__init__.py

@@ -0,0 +1,3 @@
+from obsforge.core.models import CanonicalEvent, Event, EventKind, Outcome, Severity
+
+__all__ = ["CanonicalEvent", "Event", "EventKind", "Outcome", "Severity"]

obsforge/core/contracts.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol
+
+from obsforge.core.models import Event
+from obsforge.transport.sink import SinkEnvelope
+
+
+class EventProcessor(Protocol):
+    async def process(self, event: Event) -> Event: ...
+
+    def process_sync(self, event: Event) -> Event: ...
+
+
+class EventSink(Protocol):
+    async def emit(self, envelope: SinkEnvelope) -> None: ...
+
+    def emit_sync(self, envelope: SinkEnvelope) -> None: ...
+
+
+class EventEncoder(Protocol):
+    def encode(self, event: Event) -> SinkEnvelope: ...
+
+
+class TelemetryExporter(Protocol):
+    async def export(self, event: Event) -> None: ...
+
+    def export_sync(self, event: Event) -> None: ...
+
+
+class SettingsProvider(Protocol):
+    def as_mapping(self) -> Mapping[str, Any]: ...
+
+
+class Plugin(Protocol):
+    name: str
+    version: str
+
+    def setup(self, registry: PluginRegistry) -> None: ...
+
+
+class PluginRegistry(Protocol):
+    def register_processor(self, processor: EventProcessor) -> None: ...
+
+    def register_sink(self, sink: EventSink) -> None: ...
+
+    def register_exporter(self, exporter: TelemetryExporter) -> None: ...
+
+    def register_taxonomy_namespace(self, namespace: str) -> None: ...
+
+    def processors(self) -> Sequence[EventProcessor]: ...

obsforge/core/errors.py

@@ -0,0 +1,10 @@
+class ObsforgeError(Exception):
+    """Base exception for the SDK."""
+
+
+class ConfigurationError(ObsforgeError):
+    """Raised when bootstrap or plugin setup is inconsistent."""
+
+
+class TaxonomyError(ObsforgeError):
+    """Raised when an event naming contract is invalid."""