Observability

GalaxDB exposes HTTP observability endpoints on port 9090 (configurable via --observe-port). The /health endpoint provides a quick status check, and /metrics exposes Prometheus-format metrics.

/health Endpoint

bash

GET http://localhost:9090/health

JSON

{
  "status": "ok",
  "version": "1.0.0-beta.1",
  "subsystems": {
    "disk_full": false,
    "sidecar_healthy": true,
    "connections_active": 0
  }
}

Fields:

status: "ok" or "degraded"
version: GalaxDB version string
disk_full: true if the 32 MB reserve file was consumed (writes blocked)
sidecar_healthy: true if the embedding sidecar is running and model is loaded
connections_active: number of active wire protocol connections

Tip

Use /health as a Docker health check or Kubernetes liveness probe. A non-200 response or status: "degraded" indicates a problem.

/metrics Endpoint

bash

GET http://localhost:9090/metrics

# HELP galaxdb_connections_active Number of active wire protocol connections
# TYPE galaxdb_connections_active gauge
galaxdb_connections_active 2

# HELP galaxdb_wal_write_latency_us WAL write latency in microseconds
# TYPE galaxdb_wal_write_latency_us gauge
galaxdb_wal_write_latency_us 42

# HELP galaxdb_hnsw_recall_estimate_bp HNSW recall estimate in basis points (10000 = 100%)
# TYPE galaxdb_hnsw_recall_estimate_bp gauge
galaxdb_hnsw_recall_estimate_bp 9902

# HELP galaxdb_embedding_queue_depth Embedding requests waiting to be processed
# TYPE galaxdb_embedding_queue_depth gauge
galaxdb_embedding_queue_depth 0

# HELP galaxdb_embedding_backlog_depth Embedding requests in backlog
# TYPE galaxdb_embedding_backlog_depth gauge
galaxdb_embedding_backlog_depth 0

# HELP galaxdb_checkpoint_last_duration_ms Duration of last checkpoint in milliseconds
# TYPE galaxdb_checkpoint_last_duration_ms gauge
galaxdb_checkpoint_last_duration_ms 8

# HELP galaxdb_compaction_pending_bytes Bytes pending compaction
# TYPE galaxdb_compaction_pending_bytes gauge
galaxdb_compaction_pending_bytes 0

# HELP galaxdb_buffer_pool_hot_set_usage HotSet buffer pool usage ratio
# TYPE galaxdb_buffer_pool_hot_set_usage gauge
galaxdb_buffer_pool_hot_set_usage 0.42

# HELP galaxdb_buffer_pool_scan_buffer_usage ScanBuffer pool usage ratio
# TYPE galaxdb_buffer_pool_scan_buffer_usage gauge
galaxdb_buffer_pool_scan_buffer_usage 0.15

# HELP galaxdb_sidecar_status Sidecar process status (1=healthy, 0=unhealthy)
# TYPE galaxdb_sidecar_status gauge
galaxdb_sidecar_status 1

Prometheus Integration

Add GalaxDB to your Prometheus scrape config:

YAML

# prometheus.yml
scrape_configs:
  - job_name: 'galaxdb'
    static_configs:
      - targets: ['localhost:9090']
    scrape_interval: 15s
    metrics_path: /metrics

Example Grafana dashboard queries:

# Active connections
galaxdb_connections_active

# WAL write latency (µs)
galaxdb_wal_write_latency_us

# HNSW recall (%)
galaxdb_hnsw_recall_estimate_bp / 100

# Embedding queue depth
galaxdb_embedding_queue_depth + galaxdb_embedding_backlog_depth

# Buffer pool utilization
galaxdb_buffer_pool_hot_set_usage * 100

Metrics Reference

Metric	Type	Description
galaxdb_connections_active	gauge	Active wire protocol connections
galaxdb_wal_write_latency_us	gauge	WAL write latency in microseconds
galaxdb_hnsw_recall_estimate_bp	gauge	HNSW recall estimate (basis points, 10000=100%)
galaxdb_embedding_queue_depth	gauge	Embedding requests waiting to be processed
galaxdb_embedding_backlog_depth	gauge	Embedding requests in backlog (sidecar unavailable)
galaxdb_checkpoint_last_duration_ms	gauge	Duration of last checkpoint in milliseconds
galaxdb_compaction_pending_bytes	gauge	Bytes pending compaction
galaxdb_buffer_pool_hot_set_usage	gauge	HotSet buffer pool usage ratio (0.0-1.0)
galaxdb_buffer_pool_scan_buffer_usage	gauge	ScanBuffer pool usage ratio (0.0-1.0)
galaxdb_sidecar_status	gauge	Sidecar status: 1=healthy, 0=unhealthy

Docker

Encryption