Skip to main content

Observability Configuration

Keeptrusts exposes a Prometheus-compatible gateway metrics endpoint. Use /metrics for the metric families the gateway emits. Query kt events or GET /v1/events with required since for request-level policy decisions and rejection reasons; use capture-enabled History for retained session context and Trail for control-plane audit chronology.

Supported surface​

SurfaceUse
GET /metricsPrometheus-format gateway metrics exposed on the gateway listener
GET /keeptrusts/providers/metricsProvider-level metrics for debugging routing and upstream behavior
kt events tail or GET /v1/events with required sinceRuntime request evidence and policy outcomes
History, when capture is enabledRetained request or session context
TrailControl-plane changes, audit chronology, and evidence workflows

Basic check​

Start the gateway and scrape metrics from the same listener:

kt gateway run --agent docs-observability --listen 127.0.0.1:41002 --policy-config policy-config.yaml
curl http://localhost:41002/metrics

Provider-level metrics are available separately:

curl http://localhost:41002/keeptrusts/providers/metrics

Dashboard guidance​

The default /metrics registry currently exposes:

  • kt_gateway_requests_total, labelled by HTTP method, status bucket, and provider
  • kt_gateway_policy_eval_duration_seconds, an unlabelled policy-chain latency histogram
  • kt_gateway_upstream_errors_total, labelled by provider and error type
  • cache hit and miss counters, dropped-event count, and active connections
  • Unified Access control-plane and relay counters, plus relay latency

GET /keeptrusts/providers/metrics is a JSON snapshot with per-provider sample count, TTFT and throughput percentiles, and the latest recorded health sample. Prometheus scrape health is available through the scraper's standard up series.

The gateway does not currently emit route-labelled request latency, policy verdict counts, fallback counts, or dedicated size-limit and rate-limit rejection metrics. Use status-labelled request counts for aggregate changes, kt events or the Events API for request outcomes, capture-enabled History for retained session context, and Trail for control-plane chronology. Do not build dashboards around metric names or labels that are not present in a live scrape.

Configuration boundaries​

Do not add callback or health-monitor YAML blocks to policy-config.yaml unless another product page explicitly documents them as supported configuration fields. For customer dashboards and alerts, rely on the metrics endpoints and evidence surfaces listed above.

Next steps​