Metrics

The MetricsController and PrometheusQueryService provide tenant-scoped access to Prometheus metrics. Endpoints support custom PromQL queries, pre-defined metric shortcuts, request/error rate calculations, latency percentiles, and overview dashboards.

Custom PromQL Query

Endpoint: POST /api/v1/observability/metrics/query

Executes an arbitrary PromQL query scoped to the requesting tenant.

curl -X POST http://localhost:8088/api/v1/observability/metrics/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Tenant-ID: 550e8400" \
  -d '{
    "query": "rate(http_requests_total{namespace=\"tenant-acme\"}[5m])",
    "start": "2026-02-12T09:00:00Z",
    "end": "2026-02-12T10:00:00Z",
    "step": "1m"
  }'

Pre-Defined Metrics

Endpoint: GET /api/v1/observability/metrics

Returns the list of available pre-defined metric names.

Endpoint: GET /api/v1/observability/metrics/:metricName

Parameter	Type	Default	Description
`start`	Instant	1 hour ago	Query start time
`end`	Instant	now	Query end time
`step`	String	`1m`	Step interval

Request Rates

Endpoint: GET /api/v1/observability/metrics/request-rate

Returns per-service request rates across all services in the tenant namespace.

Parameter	Type	Default	Description
`start`	Instant	1 hour ago	Start time
`end`	Instant	now	End time

Error Rates

Endpoint: GET /api/v1/observability/metrics/error-rate

Returns per-service error rates (4xx and 5xx responses).

Latency Percentiles

Endpoint: GET /api/v1/observability/metrics/latency

Returns p50, p95, and p99 latency metrics for all services. Response is a map of percentile keys to metric data.

Metrics Overview

Endpoint: GET /api/v1/observability/metrics/overview

Returns a combined overview suitable for dashboard rendering, including request rates, error rates, and p95 latency in a single response.

{
  "requestRates": { ... },
  "errorRates": { ... },
  "latencyP95": { ... },
  "timestamp": "2026-02-12T10:30:00Z"
}

Tenant Scoping

All metric queries are automatically scoped to the tenant identified by the X-Tenant-ID header. The PrometheusQueryService injects namespace filters into PromQL queries to ensure tenants can only see their own metrics.

The Observability API uses reactive Mono return types. All Prometheus queries are non-blocking, allowing the service to handle many concurrent metric requests efficiently.

Architecture Logs