Metrics & Monitoring
Relevant source files
The following files were used as context for generating this wiki page:
The Metrics & Monitoring system within the FLEXT ecosystem provides an enterprise-grade framework for collecting, managing, and orchestrating observability data. It is designed to track system performance, business-specific indicators, and service health across distributed components using standardized patterns such as Railway-Oriented Programming (ROP) and dependency injection.
The system encompasses several core capabilities, including automated function monitoring via decorators, a thread-safe custom metrics registry for domain-specific indicators, and a central orchestration layer that coordinates metrics collection, distributed tracing, and health reporting. This unified approach ensures that all FLEXT projects can implement consistent observability with minimal code duplication.
Sources: src/flext_observability/README.md:1-25, src/flext_observability/services/monitoring.py:22-35
Central Monitoring Orchestration
The FlextObservabilityMonitor serves as the central orchestrator for the monitoring system. It coordinates various observability services, including metrics, tracing, and alerting, while providing lifecycle management for these components.
Architecture and Data Flow
The monitor uses a nested class structure to organize operations and decorators, ensuring a unified pattern for execution. It integrates with FlextSettings to validate if specific features (like metrics or traces) are enabled before processing data.
The diagram above shows the flow of a monitored function call through the central orchestrator.
Sources: src/flext_observability/services/monitoring.py:38-70, src/flext_observability/services/monitoring.py:171-195
Key Methods
| Method | Description | Return Type |
|---|---|---|
flext_initialize_observability() | Initializes all services with real functionality and settings integration. | p.Result[None] |
flext_record_metric() | Records a metric entry with settings-based validation (Gauge by default). | p.Result[None] |
flext_health_status() | Resolves complete health status including uptime and function counts. | p.Result[HealthMetricsDict] |
flext_start_monitoring() | Activates real-time monitoring and service coordination. | p.Result[None] |
Sources: src/flext_observability/services/monitoring.py:145-230
Automated Function Monitoring
The system provides the @flext_monitor_function decorator to automate the collection of execution metrics. This utility tracks duration, success counts, and error rates without requiring manual instrumentation inside business logic.
Monitoring Logic
When a decorated function is executed, the MonitoringHelpers class performs the following steps:
- Initialization Check: Ensures the monitor is initialized and active.
- Timing: Captures the start time using
time.time(). - Execution: Calls the target function with provided arguments.
- Metric Recording:
- On success: Records duration (Histogram) and success count (Counter).
- On failure: Records error count (Counter), error duration (Histogram), and triggers a high-severity alert.
@flext_monitor_function(metric_name="order_processing")
def process_order(order_data: dict) -> dict:
# This function is automatically tracked for duration and errors
return {"status": "processed"}
Sources: src/flext_observability/services/monitoring.py:59-115, src/flext_observability/services/monitoring.py:270-305, examples/README.md:112-132
Custom Business Metrics
The FlextObservabilityCustomMetrics system allows projects to define and track domain-specific indicators. It utilizes a thread-safe global registry to manage metric templates for counters, gauges, and histograms.
Metric Registration Flow
Metrics are organized by namespaces (defaulting to "default") to prevent naming collisions across different services or projects.
The sequence diagram illustrates the registration and retrieval of custom business metrics.
Sources: src/flext_observability/services/custom_metrics.py:42-80, src/flext_observability/services/custom_metrics.py:168-210
Supported Metric Types
- Counter: For cumulative values (e.g., total logins).
- Gauge: For values that can go up and down (e.g., active sessions).
- Histogram: For distributions of values (e.g., request latency).
Sources: src/flext_observability/services/custom_metrics.py:20-35, src/flext_observability/models.py:160-175
Data Models
The observability entities are defined using Pydantic models in FlextObservabilityModels. These models ensure type safety and strict schema validation for all monitoring data.
| Entity | Primary Fields | Description |
|---|---|---|
Metric | name, value, unit, metric_type, labels | Standard metric data structure. |
HealthCheck | component, status, details | Represents the health state of a system component. |
ErrorEvent | error_type, message, severity, fingerprint | Used for error tracking and deduplication. |
PerformanceMetrics | operation, duration_ms, memory_used_mb, cpu_percent | Tracks internal performance of observability operations. |
Sources: src/flext_observability/models.py:40-250
Error Fingerprinting
The ErrorEvent model includes a calculate_fingerprint() method that generates a SHA256 hash based on the error type and message. This allows the system to deduplicate recurring errors and prevent alert fatigue.
Sources: src/flext_observability/models.py:202-225
Summary
The Metrics & Monitoring module provides a robust, standardized interface for system visibility. By combining the FlextObservabilityMonitor orchestrator with automated decorators and custom metric registries, the project ensures that performance and health data are collected consistently across the entire FLEXT platform. This architecture supports enterprise requirements for reliability, deduplication, and low-overhead instrumentation.
Sources: src/flext_observability/README.md:10-50