Health Checks
Relevant source files
The following files were used as context for generating this wiki page:
Health Checks in the FLEXT Observability ecosystem provide a standardized mechanism for monitoring the status and viability of various system components, such as databases, caches, and message queues. This system allows developers to define health monitoring entities with dependency validation, ensuring that high-level operational status is visible across all 33 projects in the FLEXT ecosystem.
Sources: src/flext_observability/README.md, src/README.md
The health check module is integrated into the application layer via FlextHealthService and exposed through a simplified interface for easy entity creation. It supports multiple health states—including healthy, degraded, and unhealthy—facilitating proactive system maintenance and rapid incident response.
Sources: src/flext_observability/README.md, examples/01_functional.py:72-83
Architecture and Components
The health check system follows a layered architecture, separating domain entities from application logic and external adapters.
Core Architecture Layers
| Layer | Component | Description |
|---|---|---|
| Domain | FlextHealthCheck | Core entity representing a component's health state with dependency validation. |
| Application | FlextHealthService | Coordinates health check reporting, validation, and status aggregation. |
| Interface | flext_create_health_check | A simplified API function for generating health check entities. |
| Infrastructure | HealthChecker | Utility for coordinating basic check execution patterns. |
Sources: src/flext_observability/README.md, src/README.md
Data Flow for Health Monitoring
The following diagram illustrates the flow from a service status check to the creation of an observability entity.
The system utilizes a central platform (FlextObservabilityPlatformV2) to coordinate these services across the application.
Sources: src/flext_observability/README.md, examples/01_functional.py:72-83
Health Status Levels
The system categorizes component health into distinct levels, as defined in the observability constants.
| Status | Usage Scenario | Description |
|---|---|---|
HEALTHY | Normal Operation | The component is fully functional and responding within expected parameters. |
DEGRADED | Partial Failure | The component is functional but experiencing issues (e.g., slow response or partial queue backlog). |
UNHEALTHY | Critical Failure | The component is non-functional or disconnected. |
Sources: examples/01_functional.py:72-83, examples/02_solid_observability_demo.py:84-93
Implementation Patterns
Simple API Usage
Developers can create health checks using the flext_health_check facade. This method typically requires the component name and its current status.
# Example of health check creation
from flext_observability import FlextObservability, c
# Create a healthy check for a database
result = FlextObservability.flext_health_check(
"database",
c.Observability.HealthStatus.HEALTHY
)
Sources: examples/01_functional.py:72-83, tests/unit/test_init.py:34-42
Multi-Service Monitoring
In complex environments, health checks are often performed across a sequence of services to provide a holistic view of system state.
Validation and Error Handling
The health check system employs Railway-Oriented Programming (ROP) using r[T] types. Every health check operation returns a result object that explicitly indicates success or failure.
- Success: Returns the validated
FlextHealthCheckentity. - Failure: Returns a standardized error via
create_observability_result_error(), containing details about the validation failure.
Sources: src/flext_observability/README.md, tests/README.md
Entity Validation Example
def test_flext_health_status_function() -> None:
"""Validation of health check success and entity values."""
result = flext_health_check(
"flext-observability",
c.Observability.HealthStatus.HEALTHY,
)
assert result.success == True
health_check = result.value
assert health_check.status == "healthy"
assert health_check.component == "flext-observability"
Sources: tests/unit/test_init.py:34-42
Summary
The Health Check module in flext-observability provides a robust, type-safe framework for monitoring system components. By utilizing standardized statuses (HEALTHY, DEGRADED, UNHEALTHY) and a layered architecture, it ensures that operational health is consistently tracked and reported through the FLEXT platform, facilitating efficient system diagnostics and reliability engineering.