Monitoring

ParticleDB exposes a dedicated Prometheus metrics port and health probe endpoints. This page sticks to the monitoring surfaces that are implemented in the current repo and usable from a local deployment.

Metrics Endpoint

Start the server with the metrics listener:

particledb start --metrics-port 9090

Scrape:

GET http://<host>:9090/metrics

Prometheus Example

scrape_configs:
  - job_name: "particledb"
    scrape_interval: 15s
    static_configs:
      - targets: ["localhost:9090"]

Health Endpoints

The HTTP server exposes:

GET /health — legacy plain-text OK
GET /health/live — liveness JSON
GET /health/ready — readiness JSON
GET /health/deep — deep health JSON

If you want health probes on their own port:

particledb start --health-port 8081

Example Kubernetes probes:

livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

Useful Metric Families

The exact exported set evolves, but these are representative families in the current server/registry stack:

Metric family	Purpose
`pdb_queries_total`	Query counters by type
`pdb_query_duration_seconds`	Query latency histogram
`pdb_commit_duration_seconds`	Commit latency histogram
`pdb_wal_fsync_duration_seconds`	WAL fsync latency
`pdb_connections_active`	Active connections by protocol
`pdb_memtable_bytes`	Current memtable size
`pdb_sst_files`	SST file counts by level
`pdb_disk_usage_bytes`	Approximate disk usage
`pdb_memory_rss_bytes`	Process RSS
`pdb_uptime_seconds`	Server uptime

Audit Log

If you need an in-database trail of activity, enable audit logging:

particledb start --audit-log

Then query:

SELECT * FROM __pdb_audit_log
ORDER BY timestamp DESC
LIMIT 50;

Add --audit-log-selects only if you explicitly want SELECT statements too; it can produce a lot of data.

Grafana

The repo includes an embedded Grafana dashboard template in crates/metrics/src/dashboard_template.json, plus a DashboardManager helper in spanner_metrics::dashboard.

What is available today:

Prometheus metrics on the metrics port
An embedded dashboard JSON template in the repo
A Rust helper API for provisioning Grafana

What is not currently documented as a stable end-user CLI:

A shipped particledb dashboard deploy command in the server binary

If you use Grafana, point it at your Prometheus scrape target for ParticleDB and import the template from the repo or wire up the Rust helper in your own tooling.

Diagnostic Environment Variables

Variable	Description
`PDB_WIRE_TRACE=1`	Log PG wire message flow with timing
`PDB_WIRE_DUMP=1`	Dump raw PG wire frames
`PDB_REDIS_PROFILE=1`	Log Redis command timings
`PDB_OLTP_PROFILE=1`	Log OLTP operation timings
`PDB_PARTITION_PROFILE=1`	Log OLTP partition-worker timings

Next Steps

Configuration — Ports, flags, and config keys
HTTP API — Health and status endpoints
TLS / Security — Deployment/security guidance