Monitoring & Observability
Relevant source files
The following files were used as context for generating this wiki page:
The Monitoring & Observability module in flext-oracle-oic provides tools for tracking the health and performance of Oracle Integration Cloud (OIC) instances. It is implemented via a mixin pattern that integrates with the main service facade to provide real-time status updates, component-level health checks, and performance metric analysis against defined enterprise thresholds.
Sources: src/flext_oracle_oic/services/monitoring.py:1-15, src/flext_oracle_oic/api.py:23-41
Architectural Overview
The monitoring system is structured into three layers: the Public API Facade, the Service Implementation, and the Utility Validation layer. The service layer fetches raw data from the OIC endpoints (or generates mock data if the client is not initialized), which is then passed to the utility layer for rigorous validation and threshold assessment.
Component Interaction Flow
The following diagram illustrates how a monitoring request flows from the API facade through the internal service logic and utility validation.
Health Monitoring
Health monitoring involves checking the operational status of the OIC instance and its internal components, including the database, messaging system, and integration engine.
Health Status Definitions
The system tracks four primary health states and three component-level statuses as defined in the project constants.
| Status Type | Valid Values |
|---|---|
| Overall Health | healthy, unhealthy, error, unknown |
| Component Health | healthy, unhealthy, unknown |
Sources: src/flext_oracle_oic/constants.py:133-157
Monitored Components
The system specifically targets the following internal OIC components:
- Database:
database - Messaging:
messaging - Integration Engine:
integration_engine
Sources: src/flext_oracle_oic/constants.py:159-161, src/flext_oracle_oic/services/monitoring.py:38-46
Health Check Sequence
The fetch_health_status method performs the following sequence:
Performance Metrics & Analysis
Performance metrics provide quantitative data on OIC operations. The system doesn't just collect these values; it analyzes them against configurable performance thresholds to generate automated recommendations and warnings.
Performance Thresholds
Metrics are evaluated using a validation domain that specifies the limits for "healthy" operation.
| Metric | Threshold | logic | Source File |
|---|---|---|---|
response_time_ms | 5000.0 | Critical if value > threshold | constants.py:207 |
success_rate | 0.95 (95%) | Critical if value < threshold | constants.py:208 |
error_rate | 0.05 (5%) | Warning if value > threshold | constants.py:209 |
Automated Recommendation Logic
The _assess_metric utility generates actionable insights based on the collected data.
# src/flext_oracle_oic/_utilities/monitoring.py:18-47
match metric_key:
case "average_response_time":
if metric_value > threshold:
return (f"High response time: {metric_value}ms", "Consider optimizing integration mappings", False)
case "success_rate":
if metric_value < threshold:
return (f"Low success rate: {metric_value:.2%}", "Investigate integration failures", True)
Sources: src/flext_oracle_oic/_utilities/monitoring.py:13-52
Analysis Data Structure
When performance metrics are fetched via fetch_performance_metrics, an analysis object is appended to the results containing:
- overall_health: Determined by critical issues.
- warnings: List of non-critical performance regressions.
- critical_issues: List of issues breaching critical thresholds (e.g., low success rate).
- recommendations: Suggested actions for optimization.
Sources: src/flext_oracle_oic/_utilities/monitoring.py:77-100, src/flext_oracle_oic/services/monitoring.py:168-175
Integration with API Facade
The FlextOracleOicApi class exposes monitoring functionality through synchronous and asynchronous context-aware methods. It uses the FlextOracleOicService to delegate the actual retrieval of health and performance data.
Summary
The Monitoring & Observability module provides a robust framework for maintaining OIC instance health. By combining component-level health status checks with advanced performance analysis, the system allows developers to not only detect failures but also receive automated recommendations for optimizing integration mappings and error handling. This is achieved through a strict validation layer that enforces enterprise performance thresholds across all monitored metrics.
Sources: src/flext_oracle_oic/services/monitoring.py:1-10, src/flext_oracle_oic/_utilities/monitoring.py:1-5