omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/observability/models/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Observability configuration models.
+
+This module exports configuration models for observability sinks.
+
+Note:
+    ModelMetricsPolicy and EnumMetricsPolicyViolationAction are provided by
+    omnibase_core.models.observability and omnibase_core.enums respectively.
+"""
+
+from omnibase_infra.observability.models.enum_required_log_context_key import (
+    EnumRequiredLogContextKey,
+)
+from omnibase_infra.observability.models.model_buffered_log_entry import (
+    ModelBufferedLogEntry,
+)
+from omnibase_infra.observability.models.model_logging_sink_config import (
+    ModelLoggingSinkConfig,
+)
+from omnibase_infra.observability.models.model_metrics_sink_config import (
+    ModelMetricsSinkConfig,
+)
+
+__all__: list[str] = [
+    "EnumRequiredLogContextKey",
+    "ModelBufferedLogEntry",
+    "ModelLoggingSinkConfig",
+    "ModelMetricsSinkConfig",
+]

omnibase_infra/observability/models/enum_required_log_context_key.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Required context keys for structured logging.
+
+This module defines EnumRequiredLogContextKey, a namespace class containing
+the required and recommended context keys for structured logging entries.
+
+Design Decisions:
+    - Implemented as a class with Literal-typed class attributes rather than
+      a proper Enum to avoid import complexity while maintaining type safety
+    - Provides helper methods for querying auto-added vs recommended keys
+
+See Also:
+    - ModelBufferedLogEntry: The model that uses these context keys
+    - SinkLoggingStructured: The sink that validates context keys
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+
+class EnumRequiredLogContextKey:
+    """Required context keys for structured logging.
+
+    This class defines the keys that are automatically added to every log entry
+    by the sink infrastructure. Callers should NOT include these keys in their
+    context dictionaries as they will be overwritten.
+
+    Automatically Added Keys (by SinkLoggingStructured):
+        - ORIGINAL_TIMESTAMP: ISO-8601 timestamp from emit() time
+        - LEVEL: Log level string (added by structlog processor)
+        - TIMESTAMP: ISO-8601 timestamp from flush() time (added by structlog)
+
+    Recommended Keys (callers SHOULD include):
+        - CORRELATION_ID: UUID for distributed tracing
+        - NODE_ID: ONEX node identifier
+        - OPERATION: Current operation name
+
+    Note:
+        This is implemented as a class with class attributes rather than
+        a proper Enum to avoid import complexity with EnumLogLevel while
+        maintaining a clear namespace for key constants.
+    """
+
+    # Automatically added by sink/structlog
+    ORIGINAL_TIMESTAMP: Literal["original_timestamp"] = "original_timestamp"
+    LEVEL: Literal["level"] = "level"
+    TIMESTAMP: Literal["timestamp"] = "timestamp"
+
+    # Recommended keys for callers
+    CORRELATION_ID: Literal["correlation_id"] = "correlation_id"
+    NODE_ID: Literal["node_id"] = "node_id"
+    OPERATION: Literal["operation"] = "operation"
+
+    @classmethod
+    def auto_added_keys(cls) -> frozenset[str]:
+        """Return the set of keys automatically added by the sink.
+
+        Returns:
+            Frozenset of key names that are automatically added.
+        """
+        return frozenset({cls.ORIGINAL_TIMESTAMP, cls.LEVEL, cls.TIMESTAMP})
+
+    @classmethod
+    def recommended_keys(cls) -> frozenset[str]:
+        """Return the set of recommended context keys.
+
+        Returns:
+            Frozenset of key names that callers SHOULD include.
+        """
+        return frozenset({cls.CORRELATION_ID, cls.NODE_ID, cls.OPERATION})
+
+
+__all__: list[str] = [
+    "EnumRequiredLogContextKey",
+]

omnibase_infra/observability/models/model_buffered_log_entry.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pydantic model for buffered log entries in structured logging sink.
+
+This module defines ModelBufferedLogEntry, the structured representation of
+log entries stored in the SinkLoggingStructured buffer. The model ensures
+type-safe log entry handling while supporting JSON-compatible context values.
+
+Design Decisions:
+    - Uses frozen=True for thread-safety (entries are immutable once created)
+    - Context values use JsonType for JSON serialization compatibility
+    - Required context keys are validated at flush time, not emit time,
+      to maintain hot-path performance (emit() must not block)
+
+Thread Safety:
+    ModelBufferedLogEntry is immutable (frozen=True), making instances
+    thread-safe for concurrent read access during flush operations.
+
+See Also:
+    - SinkLoggingStructured: The sink that uses this model
+    - ModelLoggingSinkConfig: Configuration model for the sink
+    - EnumRequiredLogContextKey: Required context keys enum
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.enums import EnumLogLevel
+from omnibase_core.types import JsonType
+
+
+class ModelBufferedLogEntry(BaseModel):
+    """Buffered log entry for structured logging sink.
+
+    Represents a single log entry buffered by SinkLoggingStructured. The model
+    is immutable (frozen) to ensure thread-safety when entries are accessed
+    during flush operations.
+
+    Attributes:
+        level: Log level from EnumLogLevel (DEBUG, INFO, WARNING, ERROR, etc.)
+        message: Log message content. Should be a complete, self-contained
+            message suitable for structured logging.
+        context: Structured context data for the log entry. Values may be
+            any JSON-compatible type (str, int, float, bool, None, list, dict).
+        timestamp: ISO-8601 timestamp captured at emit() time.
+
+    Context Field Types:
+        The context dictionary supports JSON-compatible value types to ensure
+        proper serialization. While dict[str, str] was previously used for
+        simplicity, JsonType allows richer context:
+
+        ```python
+        context = {
+            "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
+            "retry_count": 3,           # int is valid
+            "duration_ms": 42.5,        # float is valid
+            "is_retry": True,           # bool is valid
+            "tags": ["hot-path", "db"], # list is valid
+            "metadata": {"version": 1}, # dict is valid
+        }
+        ```
+
+    Example:
+        ```python
+        from datetime import datetime, UTC
+        from omnibase_core.enums import EnumLogLevel
+
+        entry = ModelBufferedLogEntry(
+            level=EnumLogLevel.INFO,
+            message="Database query completed",
+            context={
+                "correlation_id": "abc-123",
+                "duration_ms": 15.3,
+                "rows_affected": 42,
+            },
+            timestamp=datetime.now(UTC),
+        )
+        ```
+
+    .. versionadded:: 0.7.0
+        Replaced NamedTuple with Pydantic model for enhanced type safety.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        arbitrary_types_allowed=True,  # Allow EnumLogLevel
+    )
+
+    level: EnumLogLevel = Field(
+        ...,
+        description="Log level from EnumLogLevel enum.",
+    )
+
+    message: str = Field(
+        ...,
+        description="Log message content.",
+        min_length=1,
+    )
+
+    context: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Structured context data with JSON-compatible values.",
+    )
+
+    timestamp: datetime = Field(
+        ...,
+        description="Timestamp captured at emit() time (UTC).",
+    )
+
+
+__all__: list[str] = [
+    "ModelBufferedLogEntry",
+]

omnibase_infra/observability/models/model_logging_sink_config.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for structured logging sink.
+
+This module defines the configuration model for creating SinkLoggingStructured
+instances. The model validates configuration parameters and provides sensible
+defaults for zero-config usage.
+
+Usage:
+    ```python
+    from omnibase_infra.observability.models import ModelLoggingSinkConfig
+
+    # Default configuration (JSON output, 1000 buffer)
+    config = ModelLoggingSinkConfig()
+
+    # Custom configuration (console output, larger buffer)
+    config = ModelLoggingSinkConfig(
+        max_buffer_size=5000,
+        output_format="console",
+    )
+    ```
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelLoggingSinkConfig(BaseModel):
+    """Configuration model for structured logging sink creation.
+
+    This model defines all configurable parameters for creating a
+    SinkLoggingStructured instance. All fields have sensible defaults
+    allowing zero-config usage.
+
+    Attributes:
+        max_buffer_size: Maximum number of log entries to buffer before
+            oldest entries are dropped. Higher values use more memory but
+            reduce the chance of log loss during burst traffic.
+        output_format: Output format for log entries.
+            - "json": Machine-readable JSON format (default)
+            - "console": Human-readable colored console output
+
+    Example:
+        ```python
+        # Default configuration (JSON output, 1000 buffer)
+        config = ModelLoggingSinkConfig()
+
+        # Custom configuration (console output, larger buffer)
+        config = ModelLoggingSinkConfig(
+            max_buffer_size=5000,
+            output_format="console",
+        )
+        ```
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    max_buffer_size: int = Field(
+        default=1000,
+        ge=1,
+        description="Maximum number of log entries to buffer.",
+    )
+    output_format: str = Field(
+        default="json",
+        pattern="^(json|console)$",
+        description="Output format: 'json' or 'console'.",
+    )
+
+
+__all__: list[str] = [
+    "ModelLoggingSinkConfig",
+]

omnibase_infra/observability/models/model_metrics_sink_config.py

@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for Prometheus metrics sink.
+
+This module defines the configuration model for creating SinkMetricsPrometheus
+instances. The model validates configuration parameters and provides sensible
+defaults for zero-config usage.
+
+Usage:
+    ```python
+    from omnibase_infra.observability.models import ModelMetricsSinkConfig
+
+    # Default configuration
+    config = ModelMetricsSinkConfig()
+
+    # Custom configuration
+    config = ModelMetricsSinkConfig(
+        metric_prefix="myservice",
+        histogram_buckets=(0.001, 0.005, 0.01, 0.05, 0.1),
+    )
+    ```
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# Import from dedicated constants module (ONEX pattern: constants in constants_*.py)
+# This decouples config models from sink implementations, preventing circular imports
+# and allowing config validation without requiring the full sink dependency chain.
+from omnibase_infra.observability.constants_metrics import (
+    DEFAULT_HISTOGRAM_BUCKETS,
+)
+
+
+class ModelMetricsSinkConfig(BaseModel):
+    """Configuration model for Prometheus metrics sink creation.
+
+    This model defines the configurable parameters for creating a
+    SinkMetricsPrometheus instance. All fields have sensible defaults
+    allowing zero-config usage.
+
+    Note:
+        This config model only contains static configuration (metric_prefix,
+        histogram_buckets). Label cardinality enforcement is handled separately
+        by the sink's runtime policy, which is passed directly to the
+        SinkMetricsPrometheus constructor to enable dynamic policy updates.
+
+    Attributes:
+        metric_prefix: Optional prefix added to all metric names. Useful for
+            namespacing metrics by service or component. Empty string means
+            no prefix is added.
+        histogram_buckets: Bucket boundaries for histogram metrics. Defaults
+            to Prometheus-standard latency buckets suitable for request
+            durations in seconds. Must be positive and monotonically increasing.
+
+    Histogram Bucket Configuration:
+        Customize histogram_buckets based on your operation characteristics:
+
+        **API/HTTP Latencies (default)**: The default buckets (0.005s to 10s)
+        are optimized for typical web service request durations where most
+        requests complete in milliseconds but some may take seconds.
+
+        **Sub-millisecond Operations**: For fast operations like cache lookups,
+        in-memory computations, or high-frequency trading:
+        ``(0.0001, 0.0005, 0.001, 0.005, 0.01, 0.025, 0.05)``
+
+        **Batch Processing**: For long-running jobs, ETL pipelines, or
+        background tasks that may take minutes:
+        ``(1.0, 5.0, 10.0, 30.0, 60.0, 300.0, 600.0)``
+
+        **SLA-Aligned**: Include buckets at your SLA thresholds for alerting.
+        If your SLA is "99% of requests under 200ms", include a 0.2 bucket.
+
+        Bucket boundaries are validated to be positive and strictly ascending.
+
+    Example:
+        ```python
+        # Default configuration
+        config = ModelMetricsSinkConfig()
+
+        # Custom configuration
+        config = ModelMetricsSinkConfig(
+            metric_prefix="myservice",
+            histogram_buckets=(0.001, 0.005, 0.01, 0.05, 0.1),
+        )
+
+        # Apply config to sink
+        sink = SinkMetricsPrometheus(
+            metric_prefix=config.metric_prefix,
+            histogram_buckets=config.histogram_buckets,
+        )
+        ```
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", validate_assignment=True)
+
+    metric_prefix: str = Field(
+        default="",
+        description="Optional prefix to add to all metric names.",
+    )
+    histogram_buckets: tuple[float, ...] = Field(
+        default=DEFAULT_HISTOGRAM_BUCKETS,
+        description=(
+            "Bucket boundaries for histogram metrics in seconds. "
+            "Customize based on your operation characteristics: "
+            "API latencies (0.005-10s default), sub-millisecond operations "
+            "(0.0001, 0.0005, 0.001, 0.005, 0.01), or batch processing "
+            "(1.0, 5.0, 10.0, 30.0, 60.0, 300.0). Include buckets near "
+            "SLA thresholds for effective alerting."
+        ),
+    )
+
+    @field_validator("histogram_buckets")
+    @classmethod
+    def _validate_histogram_buckets(cls, v: tuple[float, ...]) -> tuple[float, ...]:
+        """Validate histogram bucket boundaries.
+
+        Enforces Prometheus histogram requirements:
+        1. All bucket values must be positive (> 0)
+        2. Buckets must be in strictly ascending order (monotonicity)
+
+        Args:
+            v: Tuple of bucket boundary values.
+
+        Returns:
+            The validated bucket tuple.
+
+        Raises:
+            ValueError: If any bucket is non-positive or buckets are not monotonic.
+        """
+        if not v:
+            raise ValueError("histogram_buckets cannot be empty")
+
+        # Check positivity: all values must be > 0
+        non_positive = [b for b in v if b <= 0]
+        if non_positive:
+            raise ValueError(
+                f"histogram_buckets must all be positive (> 0), "
+                f"found non-positive values: {non_positive}"
+            )
+
+        # Check monotonicity: buckets must be strictly ascending
+        for i in range(1, len(v)):
+            if v[i] <= v[i - 1]:
+                raise ValueError(
+                    f"histogram_buckets must be strictly ascending, "
+                    f"found {v[i]} <= {v[i - 1]} at index {i}"
+                )
+
+        return v
+
+
+__all__: list[str] = [
+    "ModelMetricsSinkConfig",
+]

omnibase_infra/observability/sinks/__init__.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Observability sinks for ONEX infrastructure.
+
+This module provides sink implementations for the ONEX observability stack.
+Sinks are responsible for buffering and outputting observability data
+(logs, metrics) to various backends.
+
+Available Sinks:
+    - SinkLoggingStructured: Structured logging sink using structlog
+      with JSON/console output formats and configurable buffering.
+      Implements ProtocolHotPathLoggingSink.
+    - SinkMetricsPrometheus: Thread-safe Prometheus metrics sink with
+      cardinality policy enforcement. Implements ProtocolHotPathMetricsSink.
+
+Cardinality Protection:
+    The metrics sink enforces cardinality policies via ModelMetricsPolicy
+    to prevent high-cardinality label explosions. By default, the following
+    labels are forbidden:
+        - envelope_id: Unique per-message identifier
+        - correlation_id: Request correlation identifier
+        - node_id: Node instance identifier
+        - runtime_id: Runtime instance identifier
+
+Usage:
+    ```python
+    from omnibase_infra.observability.sinks import (
+        SinkLoggingStructured,
+        SinkMetricsPrometheus,
+    )
+    from omnibase_core.enums import EnumLogLevel
+
+    # Structured logging sink
+    log_sink = SinkLoggingStructured(max_buffer_size=500, output_format="json")
+    log_sink.emit(EnumLogLevel.INFO, "Processing item", {"item_id": "123"})
+    log_sink.flush()
+
+    # Prometheus metrics sink
+    metrics_sink = SinkMetricsPrometheus()
+    metrics_sink.increment_counter(
+        "http_requests_total",
+        {"method": "POST", "status": "200"},
+    )
+    ```
+
+See Also:
+    - omnibase_spi.protocols.observability.ProtocolHotPathLoggingSink:
+      Protocol implemented by SinkLoggingStructured
+    - omnibase_spi.protocols.observability.ProtocolHotPathMetricsSink:
+      Protocol implemented by SinkMetricsPrometheus
+    - omnibase_core.models.observability.ModelMetricsPolicy:
+      Cardinality policy for metrics sinks
+"""
+
+from omnibase_infra.observability.sinks.sink_logging_structured import (
+    SinkLoggingStructured,
+)
+from omnibase_infra.observability.sinks.sink_metrics_prometheus import (
+    SinkMetricsPrometheus,
+)
+
+# Note: DEFAULT_HISTOGRAM_BUCKETS should be imported directly from
+# sink_metrics_prometheus, not from this package __init__.py.
+# This follows the pattern of importing constants from their source modules.
+
+__all__ = [
+    "SinkLoggingStructured",
+    "SinkMetricsPrometheus",
+]