obsforge 0.1.1__py3-none-any.whl

obsforge/core/models.py

@@ -0,0 +1,572 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from hashlib import sha1
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field, field_validator
+
+Scalar = str | int | float | bool | None
+
+
+class Severity(StrEnum):
+    DEBUG = "debug"
+    INFO = "info"
+    NOTICE = "notice"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+class Outcome(StrEnum):
+    UNKNOWN = "unknown"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    REJECTED = "rejected"
+    TIMEOUT = "timeout"
+    DEGRADED = "degraded"
+
+
+class EventKind(StrEnum):
+    API = "api"
+    EXCEPTION = "exception"
+    DB = "db"
+    CACHE = "cache"
+    INFRA = "infra"
+    SECURITY = "security"
+    BUSINESS = "business"
+    DEPENDENCY = "dependency"
+    APPLICATION = "application"
+
+
+class SpanKind(StrEnum):
+    INTERNAL = "internal"
+    SERVER = "server"
+    CLIENT = "client"
+    PRODUCER = "producer"
+    CONSUMER = "consumer"
+
+
+class FailureClass(StrEnum):
+    TIMEOUT = "timeout"
+    DNS = "dns"
+    SSL = "ssl"
+    CONNECTION = "connection"
+    MALFORMED_RESPONSE = "malformed_response"
+    RATE_LIMIT = "rate_limit"
+    SERVER_ERROR = "server_error"
+    CLIENT_ERROR = "client_error"
+    UPSTREAM_DEGRADED = "upstream_degraded"
+    SATURATED = "saturated"
+    UNKNOWN = "unknown"
+
+
+class DatabaseRole(StrEnum):
+    PRIMARY = "primary"
+    REPLICA = "replica"
+    UNKNOWN = "unknown"
+
+
+class ExceptionCategory(StrEnum):
+    LOGIC = "logic_failure"
+    ASYNC = "async_failure"
+    RACE = "race_condition"
+    VALIDATION = "validation_failure"
+    SERIALIZATION = "serialization_failure"
+    ORM = "orm_failure"
+    DEPENDENCY = "dependency_failure"
+    INFRASTRUCTURE = "infrastructure_failure"
+    UNKNOWN = "unknown"
+
+
+class EventDescriptor(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str
+    category: str = "application"
+    action: str | None = None
+    outcome: Outcome = Outcome.UNKNOWN
+
+
+class RuntimeContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    service_name: str = "unknown-service"
+    service_namespace: str | None = None
+    service_version: str | None = None
+    service_instance_id: str | None = None
+    deployment_environment: str = "development"
+    deployment_ring: str | None = None
+    runtime_name: Literal["cpython", "pypy"] | None = "cpython"
+    runtime_version: str | None = None
+    process_pid: int | None = None
+    host_name: str | None = 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
+    k8s_pod_name: str | None = None
+    k8s_node_name: str | None = None
+    container_name: str | None = None
+    container_image: str | None = None
+
+
+class PayloadSummary(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    kind: Literal["empty", "json", "text", "bytes", "form", "unknown"] = "unknown"
+    size_bytes: int | None = None
+    content_type: str | None = None
+    truncated: bool = False
+    key_count: int | None = None
+    top_level_keys: list[str] = Field(default_factory=list)
+    preview: str | None = None
+
+
+class RequestContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    protocol: Literal["http", "grpc", "ws", "internal"] = "http"
+    method: str | None = None
+    scheme: str | None = None
+    host: str | None = None
+    server_address: str | None = None
+    server_port: int | None = None
+    route_template: str | None = None
+    path: str | None = None
+    query_redacted: str | None = None
+    client_address: str | None = None
+    forwarded_for_redacted: str | None = None
+    user_agent: str | None = None
+    referer_redacted: str | None = None
+    content_type: str | None = None
+    body_size_bytes: int | None = None
+    timeout_ms: float | None = None
+    headers_allowlist: dict[str, str] = Field(default_factory=dict)
+    payload_summary: PayloadSummary | None = None
+
+
+class ResponseContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    status_code: int | None = None
+    status_class: Literal["1xx", "2xx", "3xx", "4xx", "5xx"] | None = None
+    content_type: str | None = None
+    body_size_bytes: int | None = None
+    malformed: bool = False
+    headers_allowlist: dict[str, str] = Field(default_factory=dict)
+    payload_summary: PayloadSummary | None = None
+
+
+class ExceptionFrame(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    file: str
+    line: int
+    function: str
+    module: str | None = None
+    class_name: str | None = None
+    locals: list[LocalVariableSnapshot] = Field(default_factory=list)
+
+
+class LocalVariableSnapshot(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str
+    type_name: str
+    preview: str | None = None
+    size_hint: int | None = None
+    redacted: bool = False
+
+
+class ExceptionCause(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    type: str
+    message: str | None = None
+    module: str | None = None
+
+
+class AsyncTaskContext(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    task_id: str | None = None
+    task_name: str | None = None
+    coroutine_name: str | None = None
+    cancelled: bool | None = None
+    loop_id: str | None = None
+    loop_debug: bool | None = None
+
+
+class ThreadContext(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    ident: int | None = None
+    native_id: int | None = None
+    name: str | None = None
+    daemon: bool | None = None
+
+
+class RuntimeStateContext(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    module: str | None = None
+    function: str | None = None
+    class_name: str | None = None
+    frame_count: int = 0
+    exception_depth: int = 0
+    locals: list[LocalVariableSnapshot] = Field(default_factory=list)
+    loop_running: bool | None = None
+    active_contexts: list[str] = Field(default_factory=list)
+
+
+class DeduplicationContext(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    fingerprint: str
+    occurrence_count: int = 1
+    duplicate: bool = False
+    first_seen_at: datetime | None = None
+    last_seen_at: datetime | None = None
+
+
+class ExceptionContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: str
+    message: str | None = None
+    error_type: str | None = None
+    category: ExceptionCategory | None = None
+    handled: bool = False
+    escaped: bool = True
+    stacktrace: str | None = None
+    frames: list[ExceptionFrame] = Field(default_factory=list)
+    cause_chain: list[str] = Field(default_factory=list)
+    causes: list[ExceptionCause] = Field(default_factory=list)
+    failure_class: FailureClass | None = None
+    runtime_state: RuntimeStateContext | None = None
+    async_context: AsyncTaskContext | None = None
+    thread_context: ThreadContext | None = None
+    deduplication: DeduplicationContext | None = None
+    normalized_message: str | None = None
+    ai_hints: list[str] = Field(default_factory=list)
+
+
+class DatabaseContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    system: str | None = None
+    namespace: str | None = None
+    database_name: str | None = None
+    host: str | None = None
+    port: int | None = None
+    role: DatabaseRole | None = None
+    alias: str | None = None
+    collection_name: str | None = None
+    operation_name: str | None = None
+    query_summary: str | None = None
+    query_fingerprint: str | None = None
+    query_text_redacted: str | None = None
+    response_status_code: str | None = None
+    rows_affected: int | None = None
+    many: bool | None = None
+    timeout_ms: float | None = None
+    deadlock_detected: bool = False
+    lock_contended: bool = False
+    retry_count: int | None = None
+    retry_storm: bool = False
+    pool_name: str | None = None
+    pool_size: int | None = None
+    pool_checked_out: int | None = None
+    pool_available: int | None = None
+    pool_waiters: int | None = None
+    pool_saturated: bool = False
+    connection_leak_suspected: bool = False
+    checkout_wait_ms: float | None = None
+    connection_reused: bool | None = None
+    connection_id: str | None = None
+    connection_age_ms: float | None = None
+    read_only: bool | None = None
+    transaction_id: str | None = None
+    transaction_depth: int | None = None
+    transaction_active: bool | None = None
+    transaction_status: str | None = None
+    transaction_isolation_level: str | None = None
+    autocommit: bool | None = None
+
+    @field_validator("autocommit", mode="before")
+    @classmethod
+    def _coerce_autocommit(cls, value: object) -> bool | None:
+        # Some drivers expose legacy/sentinel ints (e.g. sqlite's -1 = legacy
+        # transaction control). Normalize to a clean tri-state.
+        if value is None or isinstance(value, bool):
+            return value
+        if isinstance(value, int) and value in (0, 1):
+            return bool(value)
+        return None
+
+
+class CacheContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    system: Literal["redis", "memcached", "local", "other"] | None = None
+    operation: str | None = None
+    keyspace: str | None = None
+    key_hash: str | None = None
+    hit: bool | None = None
+    ttl_ms: int | None = None
+
+
+class InfrastructureContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    component_type: Literal["queue", "worker", "scheduler", "filesystem", "network", "k8s"] | None = None
+    component_name: str | None = None
+    availability_zone: str | None = None
+    node_pool: str | None = None
+    restart_count: int | None = None
+    qos_class: str | None = None
+
+
+class SecurityContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    authn_subject_hash: str | None = None
+    authn_method: str | None = None
+    authz_decision: Literal["allow", "deny", "challenge"] | None = None
+    policy_name: str | None = None
+    policy_version: str | None = None
+    mfa_present: bool | None = None
+    remote_ip_classification: Literal["private", "public", "tor", "proxy", "unknown"] | None = None
+    threat_signals: list[str] = Field(default_factory=list)
+
+
+class BusinessContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    tenant_id: str | None = None
+    tenant_hash: str | None = None
+    tenant_tier: Literal["free", "pro", "enterprise", "internal"] | None = None
+    organization_id: str | None = None
+    workspace_id: str | None = None
+    account_id: str | None = None
+    business_operation: str | None = None
+    feature: str | None = None
+    plan: str | None = None
+    transaction_id: str | None = None
+    impact_score: int | None = None
+
+
+class DependencyContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    dependency_type: Literal["http", "grpc", "db", "cache", "queue", "third_party"] | None = None
+    dependency_name: str | None = None
+    operation: str | None = None
+    target_namespace: str | None = None
+    remote_service_name: str | None = None
+    remote_region: str | None = None
+    upstream: bool | None = None
+    failure_domain: str | None = None
+
+
+class RetryContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    attempt: int | None = None
+    max_attempts: int | None = None
+    policy: str | None = None
+    backoff_ms: int | None = None
+    jitter_ms: int | None = None
+    retriable: bool | None = None
+    exhausted: bool | None = None
+    storm_detected: bool = False
+
+
+class PerformanceContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    duration_ms: float | None = None
+    queue_time_ms: float | None = None
+    db_time_ms: float | None = None
+    cpu_time_ms: float | None = None
+    memory_rss_bytes: int | None = None
+    payload_in_bytes: int | None = None
+    payload_out_bytes: int | None = None
+    slow_threshold_ms: float | None = None
+    sampled: bool | None = None
+
+
+class TraceContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    trace_id: str
+    span_id: str | None = None
+    parent_span_id: str | None = None
+    trace_flags: str | None = None
+    tracestate: str | None = None
+
+
+class TelemetryContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    trace: TraceContext | None = None
+    baggage: dict[str, str] = Field(default_factory=dict)
+    span_kind: SpanKind = SpanKind.INTERNAL
+    otel_status_code: Literal["OK", "ERROR", "UNSET"] | None = None
+    otel_status_message: str | None = None
+    telemetry_sdk_name: str | None = "opentelemetry"
+    telemetry_sdk_language: str | None = "python"
+    telemetry_sdk_version: str | None = None
+
+
+class CorrelationContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    correlation_id: str
+    request_id: str | None = None
+    causation_id: str | None = None
+    parent_event_id: str | None = None
+    workflow_id: str | None = None
+    saga_id: str | None = None
+    session_id: str | None = None
+    tenant_id: str | None = None
+    user_id: str | None = None
+    operation_id: str | None = None
+    transaction_id: str | None = None
+    idempotency_key_hash: str | None = None
+    job_id: str | None = None
+
+
+class CanonicalEvent(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal["1.0"] = "1.0"
+    event_id: str = Field(default_factory=lambda: str(uuid4()))
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    observed_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    severity: Severity = Severity.INFO
+    event_name: str
+    event_kind: EventKind = EventKind.APPLICATION
+    event_domain: str = "application"
+    operation: str | None = None
+    outcome: Outcome = Outcome.UNKNOWN
+    message: str | None = None
+    runtime: RuntimeContext = Field(default_factory=RuntimeContext)
+    correlation: CorrelationContext = Field(
+        default_factory=lambda: CorrelationContext(correlation_id=str(uuid4()))
+    )
+    telemetry: TelemetryContext = Field(default_factory=TelemetryContext)
+    request: RequestContext | None = None
+    response: ResponseContext | None = None
+    exception: ExceptionContext | None = None
+    database: DatabaseContext | None = None
+    cache: CacheContext | None = None
+    infrastructure: InfrastructureContext | None = None
+    security: SecurityContext | None = None
+    business: BusinessContext | None = None
+    dependency: DependencyContext | None = None
+    retry: RetryContext | None = None
+    performance: PerformanceContext | None = None
+    tags: dict[str, str] = Field(default_factory=dict)
+    attributes: dict[str, Scalar] = Field(default_factory=dict)
+    investigation_keys: list[str] = Field(default_factory=list)
+    ai_summary: str | None = None
+    ai_hints: list[str] = Field(default_factory=list)
+    runbook_refs: list[str] = Field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        return self.event_name
+
+    @property
+    def descriptor(self) -> EventDescriptor:
+        return EventDescriptor(
+            name=self.event_name,
+            category=self.event_domain,
+            action=self.operation,
+            outcome=self.outcome,
+        )
+
+    @property
+    def context(self) -> dict[str, Scalar]:
+        return self.attributes
+
+    @context.setter
+    def context(self, value: dict[str, Scalar]) -> None:
+        self.attributes = value
+
+    @computed_field  # type: ignore[prop-decorator]  # pydantic computed property
+    @property
+    def fingerprint(self) -> str:
+        if self.exception is not None and self.exception.deduplication is not None:
+            return self.exception.deduplication.fingerprint
+        parts = [
+            self.runtime.service_name,
+            self.event_name,
+            self.event_kind.value,
+            self.outcome.value,
+            self.request.route_template if self.request else None,
+            self.response.status_class if self.response else None,
+            self.exception.error_type if self.exception else None,
+            self.exception.type if self.exception else None,
+            self.database.system if self.database else None,
+            self.database.operation_name if self.database else None,
+            self.dependency.dependency_name if self.dependency else None,
+        ]
+        stable = "|".join(part for part in parts if part)
+        return sha1(stable.encode("utf-8"), usedforsecurity=False).hexdigest()
+
+    def loki_labels(self) -> dict[str, str]:
+        return {
+            "service": self.runtime.service_name,
+            "service_namespace": self.runtime.service_namespace or "default",
+            "environment": self.runtime.deployment_environment,
+            "level": self.severity.value,
+            "event_kind": self.event_kind.value,
+            "event_domain": self.event_domain,
+            "outcome": self.outcome.value,
+            "k8s_namespace": self.runtime.k8s_namespace_name or "none",
+            "k8s_cluster": self.runtime.k8s_cluster_name or "none",
+            "tenant_tier": (
+                self.business.tenant_tier
+                if self.business is not None and self.business.tenant_tier is not None
+                else "unknown"
+            ),
+            "runtime_name": self.runtime.runtime_name or "python",
+        }
+
+    @classmethod
+    def named(
+        cls,
+        *,
+        event_name: str,
+        severity: Severity = Severity.INFO,
+        message: str | None = None,
+        context: dict[str, Scalar] | None = None,
+    ) -> CanonicalEvent:
+        parts = event_name.split(".")
+        event_domain = parts[0] if parts else "application"
+        operation = parts[1] if len(parts) >= 2 else None
+        outcome = (
+            Outcome(parts[-1])
+            if parts and parts[-1] in Outcome._value2member_map_
+            else Outcome.UNKNOWN
+        )
+        event_kind = EventKind.API if event_domain in {"http", "api"} else EventKind.APPLICATION
+        return cls(
+            severity=severity,
+            message=message,
+            event_name=event_name,
+            event_kind=event_kind,
+            event_domain=event_domain,
+            operation=operation,
+            outcome=outcome,
+            attributes=context or {},
+        )
+
+
+Event = CanonicalEvent

obsforge/core/taxonomy.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import re
+
+from obsforge.core.errors import TaxonomyError
+
+EVENT_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){1,5}$")
+
+
+def validate_event_name(name: str) -> str:
+    if not EVENT_NAME_RE.fullmatch(name):
+        raise TaxonomyError(
+            "Event names must be lowercase dotted paths like 'auth.login.failed'."
+        )
+    return name
+
+
+class TaxonomyPolicy:
+    """Validates semantic naming and reserved namespaces."""
+
+    def __init__(self, reserved_namespaces: set[str] | None = None) -> None:
+        self._reserved_namespaces = reserved_namespaces or set()
+
+    def validate(self, name: str) -> str:
+        validate_event_name(name)
+        namespace = name.split(".", 1)[0]
+        if self._reserved_namespaces and namespace not in self._reserved_namespaces:
+            raise TaxonomyError(f"Namespace '{namespace}' is not registered.")
+        return name

obsforge/encoding/__init__.py

@@ -0,0 +1,3 @@
+from obsforge.encoding.json import OrjsonEventEncoder
+
+__all__ = ["OrjsonEventEncoder"]

obsforge/encoding/json.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+
+try:
+    import orjson
+except ImportError:  # pragma: no cover - fallback depends on local env
+    orjson = None  # type: ignore[assignment]
+
+from obsforge.core.models import Event
+from obsforge.encoding.serializers import serialize_datetime
+from obsforge.runtime.policies.loki_policy import LokiSerializer
+from obsforge.transport.sink import SinkEnvelope
+
+
+class OrjsonEventEncoder:
+    """Encodes a canonical event into a Loki-governed :class:`SinkEnvelope`."""
+
+    def __init__(self, serializer: LokiSerializer | None = None) -> None:
+        self._serializer = serializer or LokiSerializer()
+
+    def encode(self, event: Event) -> SinkEnvelope:
+        document = self._serializer.build_document(event)
+        payload = self._dumps(document)
+        return SinkEnvelope(
+            payload=payload,
+            labels=dict(document["labels"]),
+            structured_metadata=dict(document["structured_metadata"]),
+        )
+
+    def _dumps(self, payload: dict[str, Any]) -> bytes:
+        if orjson is not None:
+            return orjson.dumps(
+                payload,
+                default=self._default,
+                option=orjson.OPT_APPEND_NEWLINE | orjson.OPT_SORT_KEYS,
+            )
+        return (json.dumps(payload, default=self._default, sort_keys=True) + "\n").encode("utf-8")
+
+    @staticmethod
+    def _default(value: object) -> str:
+        if isinstance(value, datetime):
+            return serialize_datetime(value)
+        raise TypeError(f"Object of type {type(value)!r} is not JSON serializable")

obsforge/encoding/serializers.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+
+def serialize_datetime(value: datetime) -> str:
+    return value.isoformat()

obsforge/instrumentation/__init__.py

@@ -0,0 +1 @@
+"""Instrumentation subsystems for framework and transport runtimes."""

obsforge/instrumentation/db/__init__.py

@@ -0,0 +1,4 @@
+from obsforge.instrumentation.db.engine import DBObservabilityEngine
+from obsforge.instrumentation.db.state import get_default_db_engine, set_default_db_engine
+
+__all__ = ["DBObservabilityEngine", "get_default_db_engine", "set_default_db_engine"]