Source code for structum_lab.monitoring

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

"""Monitoring subsystem for Structum Framework.

Provides a pluggable metrics interface following the same pattern as logging.
Core provides the interface, plugins provide implementations (Prometheus, etc).
"""

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 metrics emitter for a namespace.

    Args:
        namespace: Metric namespace prefix (e.g., 'structum.config')

    Returns:
        MetricsInterface instance (NoOp by default, or patched by plugin)

    Example:
        >>> metrics = get_metrics("structum.config")
        >>> metrics.increment("operations.total", tags={"operation": "get"})
    """
    # 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",
]