Counters & performance

Observe the embedded engine

stats, err := db.Stats()
if err != nil {
    return err
}
fmt.Printf("seq=%d records=%d data=%d mem=%d wal=%d table=%d\n",
    stats.Sequence, stats.Records, stats.DataBytes,
    stats.MemtableBytes, stats.WALBytes, stats.SSTableRecords)

Embedded Stats is a call on the open owner. For a running server, use the authenticated GET /v1/stats HTTP endpoint; its sequence is a decimal string. The CLI stats command opens the files itself and cannot attach to another process’s handle. There is no Prometheus exporter.

Interpret the counters

• Sequence advances for nonempty mutation batches, not reads or checkpoints.
• Records counts current logical live records.
• DataBytes sums live collection/key/value lengths plus 64 per record.
• MemtableBytes includes tombstones and entries shadowing table state.
• WALBytes includes the eight-byte header and can shrink after reclamation.
• SSTableRecords is the physical current table count, which may exceed live records while tombstones remain in memory.

None is an exact heap/RSS counter, a disk-free-space check, or a filesystem quota. Sample application process memory and filesystem space independently when evaluating a workload.

Measure application behavior

Instrument call duration and returned error class at your application’s boundary. Separate durable versus relaxed writes, point reads versus scans, batch sizes, and checkpoint-triggering traffic.

Keep logs free of credentials, sensitive record values, and full sensitive keys. A collection/key identifier may itself be sensitive even when the value is omitted.

No built-in histograms, request tracing, health API, Prometheus endpoint, cache counters, or background-job telemetry exist in the current engine.

Benchmark the implementation

From the repository root:

go test -run='^$' -bench=. -benchmem -benchtime=1s -count=3 .

On PowerShell, ./benchmarks/run.ps1 records host metadata and raw output in a dated file. The checked-in baseline reports one 128-byte hot-key value, not a database larger than RAM.

BenchmarkGet separates memtable and flushed warm-cache table reads. BenchmarkPut replaces one hot key with durable/relaxed modes reported separately. These benchmarks use serial loops; a -12 suffix is not proof that twelve workers ran the workload.

Profile before optimizing

go test -run='^$' -bench=BenchmarkGet -cpuprofile=cpu.prof -memprofile=mem.prof .
go tool pprof cpu.prof
go tool pprof mem.prof

These commands produce local profile files in the repository directory. Interpret allocation profiles in the context of input copies, output ownership, encoding, and table index overhead. Do not remove correctness checks to improve a microbenchmark.

Compaction and recovery costs

The table is rewritten synchronously while holding the writer lock. Larger tables can increase write/flush tail latency and delay readers. Open verifies every table block. Measure foreground latency during automatic checkpoints and recovery time with realistic data, not just steady-state hot-key averages.

The blueprint’s latency, throughput, and memory targets remain unvalidated. See validation and the benchmark methodology.