Functional Usage Example
Relevant source files
The following files were used as context for generating this wiki page:
Functional usage in the flext-observability module demonstrates the real-world application of enterprise monitoring, metrics, and tracing within the FLEXT ecosystem. It showcases how developers can integrate observability into business logic using simple APIs, decorators, and factory patterns to achieve comprehensive visibility into system performance and health.
The implementation relies on Clean Architecture principles, ensuring that observability logic is decoupled from core business operations while providing deep insights through structured logging, distributed tracing, and domain-validated metrics.
Sources: src/README.md, examples/README.md:16-20
Core Observability API
The project provides a simplified functional API through the FlextObservability facade, allowing for the rapid creation of various observability entities without complex setup.
Entity Creation Methods
The simple API exposes several high-level functions for recording system state:
| Method | Purpose | Key Parameters |
|---|---|---|
flext_metric | Records numerical measurements. | name, value, unit |
flext_trace | Initializes a distributed trace or span. | operation_name, tags |
flext_alert | Generates system notifications. | source, title, severity |
flext_health_check | Reports the status of a component. | component, status |
flext_log_entry | Creates structured log entries. | message, severity, source |
Sources: examples/01_functional.py:27-46, src/flext_observability/README.md:52-58
API Execution Flow
The following diagram illustrates how the simple API interacts with the underlying factory and services to create observability data.
The Simple API acts as an entry point, delegating to a factory that performs domain validation before returning a Railway-Oriented result.
Sources: examples/01_functional.py:20-25, src/flext_observability/README.md:144-150
Automatic Function Monitoring
Monitoring is often achieved functionally through decorators, which automate the collection of execution time, success/failure rates, and trace propagation without manual instrumentation inside the function body.
Decorator Patterns
The @flext_monitor_function decorator is the primary tool for automated monitoring. It captures:
- Execution Time: Automatically records duration metrics.
- Trace Context: Links the function execution to a distributed trace.
- Outcome Status: Tracks if the function succeeded or failed.
@flext_monitor_function("order_processing")
def process_order(order_data: dict) -> t.JsonMapping:
"""Example of a functionally monitored business operation."""
return {"status": "processed", "order_id": order_data["id"]}
Sources: examples/README.md:113-125, src/flext_observability/README.md:111-118
Domain Validation and Railway-Oriented Results
All functional operations in flext-observability return p.Result[T], following Railway-Oriented Programming (ROP) principles. This ensures that errors are handled as data rather than exceptions, maintaining functional purity in the calling code.
Validation Logic
When a metric or trace is created, the system enforces domain business rules. For example, a metric with a negative value where only positive values are expected will return a failure result instead of throwing an error.
def demonstrate_validation() -> None:
# Successful validation
metric_result = flext_metric("valid_metric", 100.0, "count")
if metric_result.success:
_emit(f"Created metric: {metric_result.value}")
# Validation error handling
invalid_result = flext_metric("invalid_metric", -10.0, "count")
if not invalid_result.success:
_emit(f"Error: {invalid_result.error}")
Sources: examples/01_functional.py:63-75, tests/integration/test_phase_11_integration.py:53-65
Distributed Tracing and Context
Functional usage includes managing distributed context across service boundaries. This involves updating correlation IDs and trace IDs to ensure events can be linked across asynchronous operations.
Context Management Flow
The FlextObservabilityContext is used to propagate identity throughout a functional chain.
Tracing context is globally accessible within the thread/context, allowing the factory to automatically enrich entities with relevant metadata.
Sources: tests/integration/test_phase_11_integration.py:25-35, src/flext_observability/README.md:43-48
Summary of Component Responsibilities
| Component | Responsibility | Source File |
|---|---|---|
FlextObservabilityMasterFactory | Centralized creation and validation of all observability entities. | factory.py |
FlextObservabilityPlatformV2 | Orchestrates the lifecycle and communication between different services. | obs_platform.py |
FlextMetricsService | Handles the recording and exporting of validated metrics. | services.py |
FlextStructuredLogger | Manages JSON logging with correlation ID support. | flext_structured.py |
Sources: src/flext_observability/README.md:30-70
Conclusion
Functional usage in flext-observability provides a low-friction entry point for developers to implement enterprise-grade telemetry. By combining a simple facade API with robust domain validation and automated monitoring decorators, the system ensures that observability is both easy to implement and technically rigorous, adhering to the project's standards of type safety and Railway-Oriented error handling.
Sources: examples/README.md:185-195, src/README.md:30-40