Engine Stats

SHOW ENGINE STATS returns a live snapshot of node-local operational metrics from the engines embedded in the CamusDB process.

CamusDB uses Kahuna for distributed KV and transaction coordination, and Kommander for Raft and WAL coordination. Engine stats expose selected metrics from those layers through SQL, which makes it possible to inspect storage, WAL, Raft, and transaction pressure without setting up a Prometheus or OpenTelemetry pipeline first.

Syntax

SHOW ENGINE STATS;
SHOW ENGINE STATS LIKE 'raft.executor%';

LIKE filters by metric name using SQL LIKE matching. Use it when you know which subsystem you want to inspect.

SHOW ENGINE STATS LIKE 'raft.wal%';
SHOW ENGINE STATS LIKE 'kahuna.kv.write%';

This statement does not require a selected database. It can be run from camus-cli, the HTTP SQL endpoint, or the gRPC SQL endpoint.

What It Shows

Engine stats are process metrics. They are different from table statistics used by the query optimizer.

Use engine stats for questions such as:

• Is the Raft executor seeing slow operations?
• Are WAL batches coalescing many writes, or mostly flushing one operation at a time?
• Are executor queues rejecting work because a partition is overloaded?
• Did leadership churn increase during a workload?
• Are Kahuna write batches growing as expected under concurrency?

Use ANALYZE, EXPLAIN, and the query-planning pages when you need table/cardinality statistics for query plans.

Result Columns

SHOW ENGINE STATS returns one row per metric and tag set.

Column	Meaning
node	Local node or process label that produced the row.
source	Engine source, such as kahuna or kommander.
metric	Instrument name.
tags	Canonical comma-separated key=value tags. Empty when the metric has no tags.
kind	Metric kind: counter, histogram, or gauge.
count	Counter total, histogram observation count, or 1 for a sampled gauge.
total	Counter total or histogram sum. NULL for gauges.
min	Histogram minimum. NULL for counters and gauges.
max	Histogram maximum. NULL for counters and gauges.
last	Most recent histogram observation or current gauge value. NULL for counters.

Rows are ordered by source, metric, and tags, so repeated snapshots are easy to compare.

Example:

SHOW ENGINE STATS LIKE 'raft.executor.operation_duration_ms';

┌────────────────┬───────────┬──────────────────────────────────────┬────────────────────────────────────────┬───────────┬───────┬─────────┬──────┬───────┬──────┐
│ node           │ source    │ metric                               │ tags                                   │ kind      │ count │ total   │ min  │ max   │ last │
├────────────────┼───────────┼──────────────────────────────────────┼────────────────────────────────────────┼───────────┼───────┼─────────┼──────┼───────┼──────┤
│ localhost:7070 │ kommander │ raft.executor.operation_duration_ms  │ operation_class=Control,partition_id=1 │ histogram │ 12043 │ 9821.50 │ 0.01 │ 468.2 │ 0.03 │
└────────────────┴───────────┴──────────────────────────────────────┴────────────────────────────────────────┴───────────┴───────┴─────────┴──────┴───────┴──────┘

Reading Values

Counters and histograms are cumulative since the server process started. To calculate a rate or a time-window delta, run the statement twice and subtract the earlier values from the later values.

Gauges are sampled at statement time. They do not keep history, so the current value appears in last.

Useful starting points:

Metric	What To Check
raft.executor.operation_duration_ms	Operation latency by Raft partition and operation class. High max values help correlate slow dispatch warnings.
raft.executor.rejections_total	Rejected work because an executor queue was full.
raft.wal.batch_size	WAL batching density. A mean near 1 means writes are rarely coalescing.
raft.heartbeat_delay_ms	Leader heartbeat scheduling pressure.
raft.elections_started_total	Leadership churn.
kahuna.kv.write.batches	Number of KV write batches sent to storage.
kahuna.kv.write.entries	Number of KV entries written through those batches.

Node-Local Semantics

SHOW ENGINE STATS reads the current node only. It does not forward to a Raft leader and it does not aggregate across the cluster.

For a cluster-wide view, query each node and compare the node column. This is intentional: engine stats are for local runtime diagnosis, while the SQL layer keeps the statement cheap and side-effect free.

Permissions

When authentication is enabled, SHOW ENGINE STATS requires a superuser.

The statement exposes node-level workload volume, Raft topology details, and storage/WAL behavior. Those signals are broader than a single database or table grant, so regular SELECT privileges are not enough.

When authentication is disabled, the statement is available like other SQL inspection statements.

Configuration

Engine metric collection is enabled by default:

engine_metrics_enabled: true

Set it to false when you do not want CamusDB to observe embedded engine metrics:

engine_metrics_enabled: false

With collection disabled, SHOW ENGINE STATS still succeeds but returns zero rows.

This setting is independent from the diagnostics exporter configuration. SHOW ENGINE STATS can be enabled without Prometheus or OpenTelemetry, and the diagnostics exporters can be configured separately.