Observability

ShrikeDB is instrumented for health checks, namespace diagnostics, query traces, vector traces, metrics, benchmark reports, and Perfetto-compatible artifacts.

Health

Admin health server:

curl http://127.0.0.1:9190/health/live
curl http://127.0.0.1:9190/health/ready
curl http://127.0.0.1:9190/health/startup
curl http://127.0.0.1:9190/health

HTTP service convenience health:

curl http://127.0.0.1:8182/api/v1/health

Namespace Diagnostics

curl http://127.0.0.1:8182/api/v1/admin/kv/namespaces
curl http://127.0.0.1:8182/api/v1/admin/vector/namespaces
curl http://127.0.0.1:8182/api/v1/admin/multimodal/alignment

Query And Vector Traces

Endpoint Purpose

/api/v1/admin/vector/query_traces

Recent vector query traces.

/api/v1/admin/vector/query_traces/perfetto

Perfetto-compatible vector trace output.

/api/v1/admin/vector/query_traces/live

Live vector trace stream.

/api/v1/admin/vector/query_traces/config

Get or update vector trace config.

/api/v1/admin/query/plan_traces

Recent query plan traces.

/api/v1/admin/query/plan_traces/perfetto

Perfetto-compatible query plan output.

/api/v1/admin/query/plan_traces/live

Live query plan trace stream.

/api/v1/admin/query/plan_traces/config

Get or update query trace config.

Metrics

The metrics server exposes /metrics. Current metrics include lateral vector join counters and cache behavior such as:

  • outer rows,

  • actual ANN searches,

  • mean ANN latency,

  • searches per outer row,

  • cache hits,

  • in-flight singleflight hits,

  • misses,

  • bypasses.

Collect a query trace

For a query-performance investigation, retrieve recent plan traces from the HTTP listener:

curl --fail-with-body http://127.0.0.1:8182/api/v1/admin/query/plan_traces
curl --fail-with-body http://127.0.0.1:8182/api/v1/admin/query/plan_traces/perfetto \
  -o query-trace.json

Add your authentication and database-selection headers for a shared deployment. Open the exported trace in a Perfetto-compatible viewer to inspect timing. An empty trace list can mean tracing is disabled or no eligible requests have been recorded; read the trace configuration endpoint before collecting another request.

Interpret a report

Compare planning and execution time, returned rows, cache use, and fallback reasons for the same query and dataset. Vector traces also help distinguish ANN searches from graph filtering and payload hydration. Namespace reports identify which data is available when a query unexpectedly returns no rows.

Save the request, server version, configuration changes, trace, and result count together. Remove credentials before sharing diagnostics. Use Improve query performance for a repeatable performance comparison.