omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/observability/handlers/model_logging_handler_config.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for the structured logging handler.
+
+This module defines the configuration model for HandlerLoggingStructured,
+specifying buffer size, flush intervals, output format, and drop policy.
+
+Usage:
+    >>> from omnibase_infra.observability.handlers import ModelLoggingHandlerConfig
+    >>>
+    >>> # Default configuration
+    >>> config = ModelLoggingHandlerConfig()
+    >>>
+    >>> # Custom configuration
+    >>> config = ModelLoggingHandlerConfig(
+    ...     buffer_size=500,
+    ...     flush_interval_seconds=10.0,
+    ...     output_format="console",
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelLoggingHandlerConfig(BaseModel):
+    """Configuration model for the structured logging handler.
+
+    Attributes:
+        buffer_size: Maximum number of log entries to buffer before auto-flush
+            or drop policy kicks in. Default: 1000.
+        flush_interval_seconds: Interval between periodic background flushes.
+            Set to 0 to disable periodic flush. Default: 5.0.
+        output_format: Output format for log entries. Either "json" for
+            machine-readable JSON or "console" for human-readable colored output.
+            Default: "json".
+        drop_policy: Policy for handling buffer overflow. Currently only
+            "drop_oldest" is supported, which removes the oldest entries when
+            buffer is full (preserves recent logs). Default: "drop_oldest".
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", validate_assignment=True)
+
+    buffer_size: int = Field(
+        default=1000,
+        ge=1,
+        le=100000,
+        description="Maximum buffer size before drop policy applies",
+    )
+    flush_interval_seconds: float = Field(
+        default=5.0,
+        ge=0.0,
+        le=3600.0,
+        description="Periodic flush interval (0 to disable)",
+    )
+    output_format: Literal["json", "console"] = Field(
+        default="json",
+        description="Output format for log entries",
+    )
+    drop_policy: Literal["drop_oldest"] = Field(
+        default="drop_oldest",
+        description="Buffer overflow handling policy (only drop_oldest supported)",
+    )
+
+
+__all__: list[str] = [
+    "ModelLoggingHandlerConfig",
+]

omnibase_infra/observability/handlers/model_logging_handler_response.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Response model for the structured logging handler.
+
+This module defines the response model for HandlerLoggingStructured operations,
+containing operation status, buffer metrics, and correlation tracking.
+
+Usage:
+    >>> from omnibase_infra.observability.handlers import ModelLoggingHandlerResponse
+    >>> from omnibase_infra.enums import EnumResponseStatus
+    >>> from uuid import uuid4
+    >>>
+    >>> response = ModelLoggingHandlerResponse(
+    ...     status=EnumResponseStatus.SUCCESS,
+    ...     operation="logging.emit",
+    ...     message="Log entry buffered",
+    ...     correlation_id=uuid4(),
+    ...     buffer_size=42,
+    ...     drop_count=0,
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import Self
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from omnibase_infra.enums import EnumResponseStatus
+
+
+class ModelLoggingHandlerResponse(BaseModel):
+    """Response model for logging handler operations.
+
+    Attributes:
+        status: Operation status (SUCCESS or ERROR).
+        operation: The operation that was executed.
+        message: Human-readable status message.
+        correlation_id: Correlation ID for request tracing.
+        buffer_size: Current number of entries in buffer (after operation).
+        drop_count: Total number of entries dropped since handler init.
+        error_message: Error description if status is ERROR.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    status: EnumResponseStatus
+    operation: str
+    message: str
+    correlation_id: UUID
+    buffer_size: int = Field(default=0, ge=0, description="Current buffer size")
+    drop_count: int = Field(default=0, ge=0, description="Total dropped entries")
+    error_message: str | None = Field(
+        default=None,
+        description="Error description if status is ERROR",
+    )
+
+    @model_validator(mode="after")
+    def _validate_error_message_required_on_error(self) -> Self:
+        """Validate that error_message is provided when status is ERROR.
+
+        This validator ensures API consumers always receive a meaningful error
+        description when an operation fails.
+
+        Raises:
+            ValueError: If status is ERROR but error_message is None or empty.
+        """
+        if self.status == EnumResponseStatus.ERROR:
+            if not self.error_message:
+                raise ValueError("error_message is required when status is ERROR")
+        return self
+
+
+__all__: list[str] = [
+    "ModelLoggingHandlerResponse",
+]

omnibase_infra/observability/handlers/model_metrics_handler_config.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for the Prometheus metrics handler.
+
+This module defines the configuration schema for HandlerMetricsPrometheus,
+including HTTP server settings and optional push gateway configuration.
+
+Security Notes:
+    - DEFAULT BIND ADDRESS IS LOCALHOST (127.0.0.1) for security
+    - To expose externally, explicitly set host="0.0.0.0" AND deploy behind
+      a reverse proxy with authentication, TLS, and rate limiting
+    - See HandlerMetricsPrometheus docstring for full security model
+
+Configuration Options:
+    - host: Bind address for the metrics HTTP server (default: "127.0.0.1")
+    - port: Port number for the metrics endpoint (default: 9090)
+    - path: URL path for the metrics endpoint (default: "/metrics")
+    - push_gateway_url: Optional URL for Prometheus Pushgateway (for short-lived jobs)
+    - enable_server: Whether to start the HTTP server (default: True)
+    - max_request_size_bytes: Maximum allowed request body size (default: 1MB)
+    - request_timeout_seconds: Timeout for request processing (default: 30.0s)
+
+Usage:
+    >>> from omnibase_infra.observability.handlers import ModelMetricsHandlerConfig
+    >>>
+    >>> # Default configuration (localhost only - secure)
+    >>> config = ModelMetricsHandlerConfig()
+    >>> assert config.host == "127.0.0.1"  # Secure default
+    >>>
+    >>> # Expose on all interfaces (REQUIRES reverse proxy protection)
+    >>> config = ModelMetricsHandlerConfig(
+    ...     host="0.0.0.0",  # WARNING: Only use with reverse proxy
+    ...     port=9091,
+    ...     path="/custom_metrics",
+    ... )
+    >>>
+    >>> # Push mode configuration (for short-lived jobs)
+    >>> config = ModelMetricsHandlerConfig(
+    ...     enable_server=False,
+    ...     push_gateway_url="http://pushgateway:9091",
+    ... )
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelMetricsHandlerConfig(BaseModel):
+    """Configuration model for Prometheus metrics handler.
+
+    This model defines the configuration for the HTTP metrics endpoint
+    and optional push gateway integration.
+
+    Security:
+        The default bind address is "127.0.0.1" (localhost only) for security.
+        This prevents accidental exposure of metrics to untrusted networks.
+
+        To expose metrics externally, you MUST:
+        1. Explicitly set host="0.0.0.0" in configuration
+        2. Deploy behind a reverse proxy (nginx/traefik/envoy) with:
+           - TLS termination (HTTPS)
+           - IP allowlisting for Prometheus scrapers
+           - Rate limiting
+           - Authentication (mTLS or bearer tokens recommended)
+
+    Attributes:
+        host: Bind address for the HTTP server. Default: "127.0.0.1" (localhost).
+            Use "0.0.0.0" ONLY with reverse proxy protection.
+        port: TCP port number for the metrics endpoint. Standard Prometheus
+            exporters typically use ports in the 9xxx range. Default: 9090.
+        path: URL path where metrics are exposed. Must start with "/".
+            Default: "/metrics".
+        push_gateway_url: Optional URL for Prometheus Pushgateway. When set,
+            metrics can be pushed instead of scraped. Useful for short-lived
+            batch jobs that may not live long enough to be scraped.
+            Format: "http://host:port" or "https://host:port".
+        enable_server: Whether to start the HTTP server for metric scraping.
+            Set to False when using push mode only. Default: True.
+        job_name: Job name for Pushgateway metrics. Only used when pushing
+            to Pushgateway. Default: "onex_metrics".
+        push_interval_seconds: Interval between metric pushes to Pushgateway.
+            Only used when push_gateway_url is set. Default: 10.0.
+        shutdown_timeout_seconds: Maximum time to wait for graceful server
+            shutdown. Default: 5.0.
+        max_request_size_bytes: Maximum allowed request body size in bytes.
+            Requests exceeding this limit are rejected with 413 status.
+            Default: 1MB (1048576 bytes).
+        request_timeout_seconds: Timeout for processing individual requests.
+            Requests exceeding this timeout are terminated with 503 status.
+            Default: 30.0 seconds.
+
+    Example:
+        >>> # Secure default (localhost only)
+        >>> config = ModelMetricsHandlerConfig()
+        >>> assert config.host == "127.0.0.1"
+        >>> assert config.max_request_size_bytes == 1048576
+        >>>
+        >>> # External exposure (REQUIRES reverse proxy)
+        >>> config = ModelMetricsHandlerConfig(
+        ...     host="0.0.0.0",  # WARNING: Use only with reverse proxy
+        ...     port=9090,
+        ...     path="/metrics",
+        ... )
+    """
+
+    host: str = Field(
+        default="127.0.0.1",
+        description=(
+            "Bind address for the HTTP metrics server. "
+            "Default is localhost (127.0.0.1) for security. "
+            "Use 0.0.0.0 only with reverse proxy protection."
+        ),
+    )
+    port: int = Field(
+        default=9090,
+        ge=1,
+        le=65535,
+        description="Port number for the metrics endpoint",
+    )
+    path: str = Field(
+        default="/metrics",
+        pattern=r"^/.*",
+        description="URL path for the metrics endpoint",
+    )
+    push_gateway_url: str | None = Field(
+        default=None,
+        description="Optional URL for Prometheus Pushgateway",
+    )
+    enable_server: bool = Field(
+        default=True,
+        description="Whether to start the HTTP server for metric scraping",
+    )
+    job_name: str = Field(
+        default="onex_metrics",
+        description="Job name for Pushgateway metrics",
+    )
+    push_interval_seconds: float = Field(
+        default=10.0,
+        gt=0.0,
+        description="Interval between metric pushes to Pushgateway",
+    )
+    shutdown_timeout_seconds: float = Field(
+        default=5.0,
+        gt=0.0,
+        description="Maximum time to wait for graceful server shutdown",
+    )
+    max_request_size_bytes: int = Field(
+        default=1048576,  # 1MB
+        ge=1024,  # Minimum 1KB
+        le=104857600,  # Maximum 100MB
+        description=(
+            "Maximum allowed request body size in bytes. "
+            "Requests exceeding this limit are rejected with 413 status. "
+            "Default: 1MB (1048576 bytes)."
+        ),
+    )
+    request_timeout_seconds: float = Field(
+        default=30.0,
+        gt=0.0,
+        le=300.0,  # Maximum 5 minutes
+        description=(
+            "Timeout for processing individual HTTP requests. "
+            "Requests exceeding this timeout are terminated with 503 status. "
+            "Default: 30.0 seconds."
+        ),
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+__all__: list[str] = ["ModelMetricsHandlerConfig"]

omnibase_infra/observability/handlers/model_metrics_handler_payload.py

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Payload model for the Prometheus metrics handler.
+
+This module defines the payload schema for HandlerMetricsPrometheus operations,
+containing operation-specific data for metrics scrape and push operations.
+
+Usage:
+    >>> from omnibase_infra.observability.handlers import ModelMetricsHandlerPayload
+    >>>
+    >>> # Scrape response payload
+    >>> scrape_payload = ModelMetricsHandlerPayload(
+    ...     operation_type="metrics.scrape",
+    ...     metrics_text="# HELP up Scrape status\\nup 1",
+    ...     content_type="text/plain; version=0.0.4; charset=utf-8",
+    ... )
+    >>>
+    >>> # Push response payload
+    >>> push_payload = ModelMetricsHandlerPayload(
+    ...     operation_type="metrics.push",
+    ...     pushed_at="2025-01-17T12:00:00Z",
+    ...     push_gateway_url="http://pushgateway:9091",
+    ...     job_name="onex_metrics",
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class ModelMetricsHandlerPayload(BaseModel):
+    """Payload model for metrics handler operations.
+
+    Contains the operation-specific data returned by the metrics handler.
+    The structure varies based on operation_type.
+
+    Attributes:
+        operation_type: Type of operation performed. Either "metrics.scrape"
+            for metric retrieval or "metrics.push" for Pushgateway operations.
+        metrics_text: Prometheus metrics in text format. Only populated for
+            scrape operations. Contains the raw metric exposition format.
+        content_type: MIME content type for the metrics response. Standard
+            Prometheus format is "text/plain; version=0.0.4; charset=utf-8".
+        pushed_at: ISO timestamp when metrics were pushed to Pushgateway.
+            Only populated for push operations.
+        push_gateway_url: URL of the Pushgateway that received the metrics.
+            Only populated for push operations.
+        job_name: Job name used when pushing to Pushgateway.
+            Only populated for push operations.
+
+    Example:
+        >>> # Scrape response payload
+        >>> scrape_payload = ModelMetricsHandlerPayload(
+        ...     operation_type="metrics.scrape",
+        ...     metrics_text="# HELP up Scrape status\\nup 1",
+        ...     content_type="text/plain; version=0.0.4; charset=utf-8",
+        ... )
+        >>>
+        >>> # Push response payload
+        >>> push_payload = ModelMetricsHandlerPayload(
+        ...     operation_type="metrics.push",
+        ...     pushed_at="2025-01-17T12:00:00Z",
+        ...     push_gateway_url="http://pushgateway:9091",
+        ...     job_name="onex_metrics",
+        ... )
+    """
+
+    operation_type: Literal["metrics.scrape", "metrics.push"] = Field(
+        description="Type of metrics operation performed",
+    )
+    metrics_text: str | None = Field(
+        default=None,
+        description="Prometheus metrics in text exposition format",
+    )
+    content_type: str | None = Field(
+        default=None,
+        description="MIME content type for the metrics response",
+    )
+    pushed_at: str | None = Field(
+        default=None,
+        description="ISO timestamp when metrics were pushed",
+    )
+    push_gateway_url: str | None = Field(
+        default=None,
+        description="URL of the Pushgateway that received metrics",
+    )
+    job_name: str | None = Field(
+        default=None,
+        description="Job name used for Pushgateway push",
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @model_validator(mode="after")
+    def _validate_required_fields_by_operation(self) -> Self:
+        """Validate that required fields are present based on operation_type.
+
+        For metrics.scrape operations, metrics_text and content_type are required.
+        For metrics.push operations, pushed_at, push_gateway_url, and job_name
+        are required.
+
+        Raises:
+            ValueError: If required fields for the operation type are missing.
+        """
+        if self.operation_type == "metrics.scrape":
+            missing = []
+            if self.metrics_text is None:
+                missing.append("metrics_text")
+            if self.content_type is None:
+                missing.append("content_type")
+            if missing:
+                raise ValueError(
+                    f"metrics.scrape operation requires: {', '.join(missing)}"
+                )
+        elif self.operation_type == "metrics.push":
+            missing = []
+            if self.pushed_at is None:
+                missing.append("pushed_at")
+            if self.push_gateway_url is None:
+                missing.append("push_gateway_url")
+            if self.job_name is None:
+                missing.append("job_name")
+            if missing:
+                raise ValueError(
+                    f"metrics.push operation requires: {', '.join(missing)}"
+                )
+        return self
+
+
+__all__: list[str] = [
+    "ModelMetricsHandlerPayload",
+]

omnibase_infra/observability/handlers/model_metrics_handler_response.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Response model for the Prometheus metrics handler.
+
+This module defines the response schema for HandlerMetricsPrometheus operations,
+wrapping the operation payload with status and correlation tracking information.
+
+Usage:
+    >>> from omnibase_infra.observability.handlers import (
+    ...     ModelMetricsHandlerResponse,
+    ...     ModelMetricsHandlerPayload,
+    ... )
+    >>> from omnibase_infra.enums import EnumResponseStatus
+    >>> from uuid import uuid4
+    >>>
+    >>> payload = ModelMetricsHandlerPayload(
+    ...     metrics_text="# HELP http_requests_total Total HTTP requests",
+    ...     content_type="text/plain; version=0.0.4; charset=utf-8",
+    ...     operation_type="metrics.scrape",
+    ... )
+    >>> response = ModelMetricsHandlerResponse(
+    ...     status=EnumResponseStatus.SUCCESS,
+    ...     payload=payload,
+    ...     correlation_id=uuid4(),
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import Self
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from omnibase_infra.enums import EnumResponseStatus
+from omnibase_infra.observability.handlers.model_metrics_handler_payload import (
+    ModelMetricsHandlerPayload,
+)
+
+
+class ModelMetricsHandlerResponse(BaseModel):
+    """Response model for Prometheus metrics handler operations.
+
+    This is the canonical response type for all HandlerMetricsPrometheus
+    operations. It wraps the operation payload with status and correlation
+    tracking information.
+
+    Attributes:
+        status: Operation status indicating success or failure.
+        payload: Operation-specific response data.
+        correlation_id: Correlation ID for distributed tracing.
+        error_message: Error description if status is ERROR.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> response = ModelMetricsHandlerResponse(
+        ...     status=EnumResponseStatus.SUCCESS,
+        ...     payload=ModelMetricsHandlerPayload(
+        ...         operation_type="metrics.scrape",
+        ...         metrics_text="# HELP up Scrape status",
+        ...         content_type="text/plain; version=0.0.4; charset=utf-8",
+        ...     ),
+        ...     correlation_id=uuid4(),
+        ... )
+    """
+
+    status: EnumResponseStatus = Field(
+        description="Operation status (success or error)",
+    )
+    payload: ModelMetricsHandlerPayload = Field(
+        description="Operation-specific response payload",
+    )
+    correlation_id: UUID = Field(
+        description="Correlation ID for distributed tracing",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Error description if status is ERROR",
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @model_validator(mode="after")
+    def _validate_error_message_required_on_error(self) -> Self:
+        """Validate that error_message is provided when status is ERROR.
+
+        This validator ensures API consumers always receive a meaningful error
+        description when an operation fails.
+
+        Raises:
+            ValueError: If status is ERROR but error_message is None or empty.
+        """
+        if self.status == EnumResponseStatus.ERROR:
+            if not self.error_message:
+                raise ValueError("error_message is required when status is ERROR")
+        return self
+
+
+__all__: list[str] = [
+    "ModelMetricsHandlerResponse",
+]

omnibase_infra/observability/hooks/__init__.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pipeline hooks for cross-cutting observability concerns.
+
+This module provides hooks that can be integrated into infrastructure pipelines
+to enable observability instrumentation without modifying the core business logic.
+
+Key Components:
+    - HookObservability: Pipeline hook for timing, metrics, and context tracking
+    - get_global_hook(): Thread-safe access to a global singleton hook
+    - configure_global_hook(): Configure the global singleton on first use
+    - clear_global_hook(): Reset the singleton for reconfiguration or testing
+    - has_global_hook(): Check if a singleton exists
+
+Design Philosophy:
+    Hooks use contextvars for all per-operation state to ensure concurrency
+    safety in async code. This is a CRITICAL design decision - using instance
+    variables for timing state would cause race conditions when multiple
+    concurrent operations use the same hook instance.
+
+    The module also provides optional singleton support via get_global_hook()
+    for applications that need a shared observability hook across components.
+    The singleton is thread-safe and logs a warning when configuration is
+    ignored for an existing instance.
+
+Usage Example:
+    ```python
+    from omnibase_infra.observability.hooks import HookObservability
+    from omnibase_spi.protocols.observability import ProtocolHotPathMetricsSink
+
+    # Create hook with optional metrics sink
+    sink: ProtocolHotPathMetricsSink = get_metrics_sink()
+    hook = HookObservability(metrics_sink=sink)
+
+    # Use context manager for automatic timing
+    with hook.operation_context("handler.process", correlation_id="abc-123"):
+        result = await handler.execute(payload)
+
+    # Or use manual timing for more control
+    hook.before_operation("db.query", correlation_id="abc-123")
+    try:
+        result = await db.execute(query)
+        hook.record_success()
+    except Exception as e:
+        hook.record_failure(type(e).__name__)
+        raise
+    finally:
+        duration_ms = hook.after_operation()
+
+    # Or use the global singleton
+    from omnibase_infra.observability.hooks import get_global_hook
+    hook = get_global_hook(metrics_sink=sink)  # Returns singleton
+    ```
+
+See Also:
+    - ProtocolHotPathMetricsSink: Metrics collection protocol
+    - correlation.py: Correlation ID management (same contextvar pattern)
+"""
+
+from omnibase_infra.observability.hooks.hook_observability import (
+    HookObservability,
+    clear_global_hook,
+    configure_global_hook,
+    get_global_hook,
+    has_global_hook,
+)
+
+__all__ = [
+    "HookObservability",
+    "get_global_hook",
+    "configure_global_hook",
+    "clear_global_hook",
+    "has_global_hook",
+]