Observability API Architecture
The Observability API provides a unified interface for metrics, logs, traces, dashboards, alerting, SLOs, anomaly detection, capacity planning, cost allocation, custom metrics, and profiling across the MATIH platform. Running on port 8088, it aggregates data from Prometheus, Loki, and Jaeger into a tenant-scoped, multi-signal observability layer with reactive (WebFlux) endpoints.
Service Overview
| Property | Value |
|---|---|
| Service Name | observability-api |
| Port | 8088 |
| Technology | Spring Boot 3.2, Java 21, Spring WebFlux (reactive) |
| Metrics Backend | Prometheus |
| Logs Backend | Loki |
| Traces Backend | Jaeger |
| Database | PostgreSQL (benchmarks, reports) |
| API Documentation | OpenAPI 3.0 (Swagger) |
Controllers
| Controller | Base Path | Purpose |
|---|---|---|
MetricsController | /api/v1/observability/metrics | PromQL queries, request/error rates, latencies |
LogsController | /api/v1/observability/logs | Log querying and streaming |
TracingController | /api/v1/observability/traces | Distributed trace search and analysis |
DashboardController | /api/v1/observability/dashboards | Dashboard templates and customization |
AlertingController | /api/v1/observability/alerts | Alert rules and notification management |
SLOController | /api/v1/observability/slos | Service level objective management |
AnomalyDetectionController | /api/v1/observability/anomalies | ML-based anomaly detection |
CapacityPlanningController | /api/v1/observability/capacity | Resource utilization and forecasting |
CostAllocationController | /api/v1/observability/costs | Observability cost allocation |
CustomMetricsController | /api/v1/observability/custom-metrics | Custom metric registration and queries |
ProfilingController | /api/v1/observability/profiling | Continuous profiling |
RealtimeDashboardController | -- | WebSocket real-time dashboards |
TopologyController | -- | Service dependency mapping |
HealthScoreController | -- | Health scoring |
HealthController | /health | Service health probes |
Reactive Architecture
The Observability API uses Spring WebFlux for non-blocking, reactive request handling. Most endpoints return Mono or Flux types, allowing efficient concurrent querying of multiple backends (Prometheus, Loki, Jaeger) without thread blocking.
Next Steps
- Metrics -- Prometheus metric queries
- Logs -- Loki log queries
- Tracing -- Jaeger trace analysis
- Dashboards -- dashboard templates
- Alerting -- alert rules
- SLOs -- service level objectives
- Anomaly Detection -- ML anomaly detection
- Capacity Planning -- resource forecasting
- Cost Allocation -- observability costs
- Custom Metrics -- user-defined metrics
- Profiling -- continuous profiling
- API Reference -- complete endpoint listing