feat(cmd): add --mem-profile flag and BEADS_MEM_PROFILE env var (be-tg2o)

Adds heap profiling parity with the existing --profile (CPU) flag:
- --mem-profile FILE writes a pprof heap snapshot on exit
- BEADS_MEM_PROFILE=FILE env var fallback for scripting
- BEADS_MEM_PROFILE_NOGC=1 skips the pre-write GC to capture peak allocation
- BEADS_MEM_STATS=FILE writes a one-line HeapAlloc/HeapSys/HeapInuse/HeapObjects summary

Documents all four knobs in docs/CONFIG.md §Profiling.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Jim Wordelman 2026-05-12 14:03:59 -07:00
commit d05741f100
2 changed files with 65 additions and 0 deletions

View file

@ -7,6 +7,7 @@ import (
"os/exec"
"os/signal"
"path/filepath"
"runtime"
"runtime/pprof"
"runtime/trace"
"slices"
@ -76,6 +77,7 @@ var (
profileEnabled bool
profileFile *os.File
traceFile *os.File
memProfilePath string
verboseFlag bool // Enable verbose/debug output
quietFlag bool // Suppress non-essential output
@ -506,6 +508,7 @@ func init() {
rootCmd.PersistentFlags().BoolVar(&globalFlag, "global", false, "Use the global shared-server database (beads_global)")
rootCmd.PersistentFlags().StringVar(&doltAutoCommit, "dolt-auto-commit", "", "Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit")
rootCmd.PersistentFlags().BoolVar(&profileEnabled, "profile", false, "Generate CPU profile for performance analysis")
rootCmd.PersistentFlags().StringVar(&memProfilePath, "mem-profile", "", "Write heap profile to FILE on exit (also respects BEADS_MEM_PROFILE)")
rootCmd.PersistentFlags().BoolVarP(&verboseFlag, "verbose", "v", false, "Enable verbose/debug output")
rootCmd.PersistentFlags().BoolVarP(&quietFlag, "quiet", "q", false, "Suppress non-essential output (errors only)")
@ -1162,6 +1165,32 @@ var rootCmd = &cobra.Command{
_ = traceFile.Close() // Best effort cleanup
}
// Heap profiling: --mem-profile flag or BEADS_MEM_PROFILE env var.
// Runs a GC first by default; BEADS_MEM_PROFILE_NOGC=1 skips it to capture peak.
heapDest := memProfilePath
if heapDest == "" {
heapDest = os.Getenv("BEADS_MEM_PROFILE")
}
if heapDest != "" {
if os.Getenv("BEADS_MEM_PROFILE_NOGC") == "" {
runtime.GC()
}
if f, err := os.Create(heapDest); err == nil { // #nosec G304 -- user-supplied profiling path
_ = pprof.WriteHeapProfile(f)
_ = f.Close()
}
}
// Optional one-line MemStats summary: BEADS_MEM_STATS=/path/to/stats.txt
if statsDest := os.Getenv("BEADS_MEM_STATS"); statsDest != "" {
var ms runtime.MemStats
runtime.ReadMemStats(&ms)
if f, err := os.Create(statsDest); err == nil { // #nosec G304 -- user-supplied profiling path
fmt.Fprintf(f, "HeapAlloc=%d HeapSys=%d HeapInuse=%d HeapObjects=%d\n",
ms.HeapAlloc, ms.HeapSys, ms.HeapInuse, ms.HeapObjects)
_ = f.Close()
}
}
// Cancel the signal context to clean up resources
if rootCancel != nil {
rootCancel()

View file

@ -992,6 +992,42 @@ Some bd commands automatically use configuration:
External integration scripts can read configuration to sync with Jira, Linear, GitHub, etc.
## Profiling
### CPU Profiling
```bash
bd list --profile # writes bd-profile-list-<timestamp>.prof + .out trace
go tool pprof bd-profile-list-*.prof
```
### Heap / Memory Profiling
Use `--mem-profile` or the `BEADS_MEM_PROFILE` env var to write a heap profile on exit:
```bash
bd list --mem-profile /tmp/h.prof
go tool pprof /tmp/h.prof
# Env var form (useful in scripts)
BEADS_MEM_PROFILE=/tmp/h.prof bd list
```
By default a `runtime.GC()` fires before writing so the profile shows live objects.
To capture peak allocation instead, set `BEADS_MEM_PROFILE_NOGC=1`:
```bash
BEADS_MEM_PROFILE=/tmp/h.prof BEADS_MEM_PROFILE_NOGC=1 bd list
```
For a quick one-line summary without opening pprof:
```bash
BEADS_MEM_STATS=/tmp/stats.txt bd list
cat /tmp/stats.txt
# HeapAlloc=12345 HeapSys=67890 HeapInuse=34567 HeapObjects=890
```
## See Also
- [README.md](../README.md) - Main documentation