Source code for structum.monitoring

# src/structum/monitoring/__init__.py
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: 2025 PythonWoods

"""
Monitoring subsystem for Structum Framework.

**Architectural Role**:
This module acts as the **Observability Facade** (DP-6). It provides a unified,
safe API for emitting metrics (`get_metrics()`) that:
1.  **Never Fails**: Uses Null Objects (`NoOpMetrics`) if no backend is configured.
2.  **Zero Coupling**: Application code doesn't import Prometheus or Datadog libraries.
3.  **Hot-Patchable**: Plugins inject the real backend at runtime.
"""

from .interfaces import MetricsInterface, NoOpMetrics

# Global metrics instance (can be patched by plugins)
_metrics_instance: MetricsInterface = NoOpMetrics()



[docs]
def get_metrics(namespace: str = "structum") -> MetricsInterface:
    """
    Get (or create) a metrics emitter for a specific namespace.

    **Architectural Role**: Factory Accessor.

    This function isolates the application from the instantiation complexity
    of metric backends.

    Args:
        namespace: Logical grouping (e.g., 'structum.database', 'myapp.orders').

    Returns:
        MetricsInterface: A thread-safe metrics emitter (NoOp or Real).
    """
    # For now, return the global instance
    # Plugins can patch _metrics_instance
    return _metrics_instance




[docs]
def set_metrics_backend(backend: MetricsInterface) -> None:
    """Set the global metrics backend.

    This is called by monitoring plugins (e.g., structum_observability)
    to inject their implementation.

    Args:
        backend: MetricsInterface implementation
    """
    global _metrics_instance
    _metrics_instance = backend



__all__ = [
    "MetricsInterface",
    "NoOpMetrics",
    "get_metrics",
    "set_metrics_backend",
]