jemalloc Heap Profiling Runbook

Operator runbook for memory/heap analysis based on jemalloc. Canonical source: this runbook in angarabook/src/operations/.

Scope

• feature: jemalloc-prof (opt-in);
• heap-fragmentation metrics;
• on-demand profiling in staging/debug;
• leak-check for long-running runs (Golden DB).

Build and verify

cargo build --release --features jemalloc-prof
curl http://localhost:9091/metrics | rg jemalloc

Key metrics

• angarabase_jemalloc_allocated_bytes
• angarabase_jemalloc_resident_bytes
• angarabase_jemalloc_active_bytes
• angarabase_jemalloc_mapped_bytes
• angarabase_jemalloc_fragmentation_ratio

Practical interpretation:

• ~1.0: low fragmentation;
• >1.5: fragmentation risk;
• >2.0: memory path investigation required.

Heap profiling workflow

1. Start with MALLOC_CONF=prof:true,....
2. Send SIGUSR1 for forced dump.
3. Analyze with jeprof (text/pdf/diff).

Leak-check for long-lived runs

Golden DB flow:

• tools/golden_db/manage.sh leak-check baseline
• long-running load
• tools/golden_db/manage.sh leak-check report

Compare baseline/after by allocated/resident/mapped and fragmentation.

Related references

• tools/golden_db/manage.sh
• src/operations/golden-dataset.md