Core Monitoring Module¶

Package: structum-core (module structum.monitoring)
Status: Core Protocol
Dependencies: Zero (Python Standard Library only)

Overview¶

[!NOTE] Architectural Role: This module is part of the Foundation Layer.
See Enterprise Architecture Guide for the full architectural map.

The Core Monitoring module defines the Metrics Interfaces for the framework. Like logging, it decouples instrumentation from the collection backend (Prometheus, StatsD, Datadog, etc.).

This allows you to instrument your code with metrics without locking yourself into a specific monitoring vendor.

MetricsInterface¶

The MetricsInterface protocol defines standard metric types.

class MetricsInterface(Protocol):
    def increment(self, name: str, value: float = 1.0, tags: dict = None) -> None: ...
    def gauge(self, name: str, value: float, tags: dict = None) -> None: ...
    def timing(self, name: str, value: float, tags: dict = None) -> None: ...
    def histogram(self, name: str, value: float, tags: dict = None) -> None: ...

Metric Types¶

Counter (increment): Monotonic value (goes up). E.g., requests_total.
Gauge (gauge): Instantaneous value (up/down). E.g., memory_used.
Timing (timing): Durtation of an event. E.g., db_query_latency.
Histogram (histogram): Statistical distribution. E.g., response_size.

Usage¶

Getting Metrics¶

from structum.monitoring import get_metrics

# Returns a NoOpMetrics if no plugin is installed, or the real backend
metrics = get_metrics()

Instrumenting Code¶

def process_queue():
    # Gauge: Current state
    metrics.gauge("queue.size", len(queue))
    
    start_time = time.time()
    try:
        item = queue.pop()
        process(item)
        
        # Counter: Event tracking
        metrics.increment("items_processed", tags={"status": "success"})
    except Exception:
        metrics.increment("items_processed", tags={"status": "error"})
    finally:
        # Timing: Latency
        duration = time.time() - start_time
        metrics.timing("process.duration", duration)

Operational Continuity¶

Structum guarantees Operational Continuity:

If structum-observability is installed: Metrics are sent to Prometheus/OTEL.
If NOT installed: Calls go to NoOpMetrics, which silently discards them.

Benefit: You can add metrics to shared libraries without forcing consumers to install heavy monitoring dependencies.