Performance Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Performance Tracking within the FLEXT Observability framework provides specialized tools for monitoring the overhead of observability operations themselves, ensuring that instrumentation does not negatively impact production environments. It encompasses tracking execution latency, memory consumption, and CPU utilization across various observability tasks such as tracing, metrics collection, and context propagation.
This system is designed to provide high-level validation of performance metrics against predefined thresholds (e.g., HTTP instrumentation overhead) and facilitates production-grade optimization by identifying bottlenecks in telemetry generation.
Sources: src/flext_observability/services/performance.py:1-13, tests/e2e/README.md:144-149
Core Architecture and Components
The performance tracking system is primarily implemented through the FlextObservabilityPerformance service. This service provides a nested Monitor class that captures the delta in resource usage for specific operations.
Performance Monitoring Service
The FlextObservabilityPerformance class serves as the orchestrator for performance checks. It utilizes psutil to interface with system-level process information and provides static methods for resource fetching and threshold validation.
Sources: src/flext_observability/services/performance.py:25-30
Operation Monitor
The Monitor nested class is the primary unit of execution for tracking. It captures initial state (memory and CPU) upon instantiation and calculates final metrics upon completion.
Sources: src/flext_observability/services/performance.py:53-73
The following diagram illustrates the flow of performance monitoring for an individual operation:
A flowchart showing the lifecycle of a performance monitoring session from initialization to metric calculation.
Sources: src/flext_observability/services/performance.py:34-48, src/flext_observability/services/performance.py:75-88
Resource Tracking Logic
The system tracks three primary categories of resource utilization to determine the "overhead" of an observability call.
Monitored Resource Metrics
| Metric | Description | Data Source |
|---|---|---|
| Duration (ms) | Total execution time of the monitored block. | time.time() |
| Memory (MB) | Resident Set Size (RSS) delta during the operation. | psutil.Process().memory_info() |
| CPU (%) | Process CPU utilization percentage during the window. | psutil.Process().cpu_percent() |
Sources: src/flext_observability/services/performance.py:100-128
System Resource Fetching
Beyond individual monitors, the system can fetch global process state via fetch_system_resources(), which returns a mapping of memory_mb, memory_percent, and cpu_percent.
Sources: src/flext_observability/services/performance.py:121-141
Performance Validation Thresholds
The system enforces specific latency thresholds to ensure observability operations remain within acceptable limits. These are validated via the performance_acceptable method.
| Operation Prefix | Acceptable Overhead (ms) |
|---|---|
http_ | < 50.0 ms |
database_ | < 100.0 ms |
context_ | < 10.0 ms |
sampling_ | < 5.0 ms |
default | < 100.0 ms |
Sources: src/flext_observability/services/performance.py:157-175
A sequence diagram depicting the interaction between application code and the performance service to validate operation overhead.
Sources: tests/integration/test_phase_11_integration.py:154-165, src/flext_observability/services/performance.py:143-145
Integration with Observability Context
Performance tracking is frequently integrated into the broader observability workflow to validate the efficiency of context propagation and distributed tracing.
- Sampling Validation: Performance monitors are used to ensure that the
should_sampledecision logic does not exceed a 5ms overhead. - Integration Testing: Phase 11 integration tests utilize
FlextObservabilityPerformanceto wrap E2E workflows, validating that "workflow.duration_ms" matches the tracked monitor duration. - Logging: Metrics are logged via
log_performance_metrics, which maps performance data to structured log levels (DEBUG for success, WARNING for failure or high overhead).
Sources: tests/integration/test_phase_11_integration.py:154-165, tests/integration/test_phase_11_integration.py:186-193, src/flext_observability/services/performance.py:180-205
Summary
Performance Tracking in FLEXT Observability provides the essential guardrails for production instrumentation. By utilizing the FlextObservabilityPerformance service and its Monitor component, the system captures granular resource deltas and validates them against strict enterprise latency thresholds. This ensures that the observability stack provides visibility without compromising the performance of the underlying business applications.