What it does
The server exposes Prometheus text metrics at /metrics, per-route latency percentiles and error rates for administrators, liveness and readiness probes, a request id on responses, a log warning for slow requests, structured logs and optional OTLP trace export. The retrieval objectives and the alert webhooks are described under their own entry.
How it works
GET /metrics returns Prometheus text. It is private by default and needs the global service key unless KYNETRA_PUBLIC_METRICS is true. A scrape that did not present the service key never sees the gauges that show write-log progress, such as the log sequence and replica lag, even when public metrics are on.
A middleware times every request and records its matched route template, so /v1/entities/{id} is one series and not one per id. The same measurement feeds the Prometheus counters and an in-memory per-route tracker with p50, p95 and p99 latency and an error rate, which an administrator reads at GET /admin/db/slo. The tracker keeps one cumulative histogram per route since process start. It resets on restart and is not a rolling window.
GET /healthz is a liveness probe and GET /readyz reports readiness, including whether log replay has finished. Neither asks for credentials, so a load balancer can use them. An unauthenticated caller to /readyz gets the status code, the overall status and a good-or-bad flag per check; the full body, with replication positions, goes to a caller holding the global service key. An engine that is fenced after an unresolved recovery fault reports not ready while liveness stays healthy. GET /admin/health gives administrators the detailed checks.
Every response carries x-request-id. The server reuses a valid id sent by the caller and generates one otherwise, and the id is attached to every log line written while the request runs. Requests that run longer than the KYNETRA_SLOW_QUERY_MS threshold (100 milliseconds by default) on the watched route prefixes in KYNETRA_SLOW_QUERY_ROUTES are logged at warning level with the route, status and duration. KYNETRA_LOG_FORMAT=json switches to structured logs, and setting OTEL_EXPORTER_OTLP_ENDPOINT exports spans over OTLP/HTTP to a collector.
Where you reach it
- HTTP
GET /metrics (Prometheus text; service key required unless KYNETRA_PUBLIC_METRICS=true) - HTTP
GET /admin/db/slo (per-route latency percentiles and error rate) - HTTP
GET /healthz, GET /readyz, GET /admin/health - Config
KYNETRA_SLOW_QUERY_MS, KYNETRA_SLOW_QUERY_ROUTES, KYNETRA_LOG_FORMAT, OTEL_EXPORTER_OTLP_ENDPOINT, KYNETRA_PUBLIC_METRICS
Limits
- The per-route tracker is in memory and cumulative since the process started. It resets on restart and reports no recent-window rate.
- Metrics describe one instance. Aggregation across instances is up to your monitoring system.
- Slow requests are written to the log. They are not stored as records or searchable in the admin console.
- Trace export is off unless OTEL_EXPORTER_OTLP_ENDPOINT is set, and the OTLP endpoint is one you operate.
Evidence
- On this siteDocumentation hub: operations
- On this siteAPI reference: public routes
- TestsCovered in the engine repository by 10 metrics tests, 3 SLO tracker tests, 4 slow-request tests and 3 correlation-id tests in the observability crate, and mounted-router tests that /metrics is private by default and never shows write-log progress to an unauthenticated scrape
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to try this against your own workload.