[zackees]

What

The daemon's heap dumps are only half a diagnostic: they carry raw addresses
plus a mapping table and zero function entries, so a reader who points a
symbolizer at the installed release binary gets ??:? and concludes nothing is
leaking. This adds the missing half — the procedure and the symbolization
requirement — and fixes a message whose literal had 20+ spaces baked into it.

1. docs/guides/heap-profiling.md (new) — how to capture from process start
   (FBUILD_HEAP_PROFILE=1) and on demand (POST /api/daemon/heap-dump), where
   dumps land, and how to symbolize them. Calls out that wheels ship stripped
   binaries and that the matching fbuild-<version>-<target>-debug sidecar from
   the same GitHub release is what names frames. Includes the measured
   unstripped-vs-stripped table below.
2. crates/fbuild-daemon/src/handlers/health.rs — the on-demand-dump message was
   one source line wrapped without continuations, so it rendered as
   with this request … the ones already held. Now single-spaced, and both branches name the binary/sidecar needed to
   symbolize the result.
3. docs/guides/README.md + docs/INDEX.md — two routing rows, so the page is
   reachable from the documented entry points.

Why this is #1360's "make sure it actually works" half

#1360's open headline is the ~3.9 GB idle leak; the review asked for the
symbolization path to be checked before the wiring is called done. This does
that against a real release daemon and records the answer.

Verification (real output)

Built the daemon and captured a dump end-to-end on Linux:

$ soldr cargo build --release -p fbuild-daemon
    Finished `release` profile [optimized + debuginfo] target(s) in 6m 13s
  171 MB unstripped / 46 MB after strip

$ FBUILD_HEAP_PROFILE=1 ./target/release/fbuild-daemon --dev --port 8977 &
$ curl -s 127.0.0.1:8977/health
{"status":"healthy","version":"2.5.49","build_id":"be6059a938af","pid":790877,...}

$ curl -s -X POST 127.0.0.1:8977/api/daemon/heap-dump
{"path":".../heap-profiles/heap-790877-...pb","live_samples":5,
 "profiling_was_already_running":true,"message":"heap snapshot written"}

Dump contents: 5 samples, 12 locations, 8 mappings, 0 functions — addresses
only, exactly as documented. Same addresses, base-subtracted, through
addr2line -f -C -e <binary>:

offset	unstripped release binary	stripped copy
0x2adb09a	_mi_prof_stack_intern (mimalloc-pprof-amalgamated.c:21444)	pthread_create
0x2adcb0b	_mi_prof_on_alloc (mimalloc-pprof-amalgamated.c:21253)	pthread_create
0x2adfc69	mi_page_malloc_zero (mimalloc-pprof-amalgamated.c:7171)	pthread_create
0x2aa4b8a	tokio::runtime::scheduler::multi_thread::worker::create	??:?
0x2764ab8	fbuild_core::usb::profiles::validate_and_index (profiles.rs:49)	??:?

Gates:

$ soldr cargo fmt --all -- --check                                   # rc 0
$ SOLDR_VERDICTS=off soldr cargo check -p fbuild-daemon --all-targets # rc 0
$ SOLDR_VERDICTS=off soldr cargo test -p fbuild-daemon --lib          # 297 passed, 0 failed, 3 ignored
$ SOLDR_VERDICTS=off soldr cargo test -p fbuild-daemon --lib health   # 9 passed, 0 failed
$ SOLDR_VERDICTS=off soldr cargo test -p fbuild-cli --bin fbuild multicall # 7 passed
$ uv run --no-project python ci/enforce_platform_boundary.py --print-totals # rows=44; dylint_rows=43, rc 0
$ uv run --no-project python ci/check_test_layout.py                  # ok: 8 categories, rc 0

Documentation only beyond the message string; no daemon behavior changed.

Refs #1360. Does not close it — the leak itself is still undiagnosed.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: FastLED/fbuild
• Branch: agent/1360-heap-symbolize
• File: .coderabbit.yaml
• Commit: 5047934
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9d77a972-3ff0-4dfd-ae31-07df75cc4dba

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn