Add profiling_hooks feature exposing jemalloc's experimental sample hooks

[scottgerring]

Addresses #160, adding a profiling_hooks feature to tikv-jemalloc-sys (forwarded through tikv-jemalloc-ctl) exposing jemalloc's experimental experimental.hooks.prof_sample/prof_sample_free/prof_backtrace hooks, so an external sampler (e.g. an eBPF profiler) can piggyback jemalloc's sampling decision without using its stack walking. Over in opentelemetry world, we are looking at adding heap profiling to https://github.com/open-telemetry/opentelemetry-ebpf-profiler and this would give us a way of providing sample points for it to use for folks running jemalloc.

Since jemalloc-sys has links = "jemalloc", there's only one build per dependency graph, so this bakes prof:true,prof_active:false into the default malloc_conf — sampling is installable but inert until a consumer flips prof.active at runtime, avoiding surprises for other dependents.

Also adds prof_active (r/w/u) and prof_reset (w/o) runtime controls to tikv_jemalloc_ctl::profiling (always compiled under profiling), plus the hook setters and a noop_prof_backtrace_hook for callers that only want the sampling clock - this is helpful, again, on the eBPF profiler side, as it has all the stack unwinding stuff built in, and we can avoid paying the cost twice.

No USDT/eBPF emission included; just the hook-registration API for a downstream consumer to build on.

Summary by CodeRabbit

• New Features

  • Added optional profiling hooks for allocation, deallocation, and backtrace events.
  • Added runtime controls to activate profiling and reset sampling behavior.
  • Added APIs for installing, replacing, and removing profiling hooks.
  • Profiling hooks are inactive by default until explicitly enabled.

• Documentation

  • Documented the new profiling_hooks feature, runtime behavior, and available hook APIs.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds a profiling_hooks feature, configures jemalloc profiling defaults, exposes profiling controls and hook setters, documents the APIs, and adds feature-gated integration tests.

Changes

Profiling hooks support

Layer / File(s)	Summary
jemalloc profiling feature configuration jemalloc-sys/Cargo.toml, jemalloc-sys/build.rs, jemalloc-sys/README.md	Adds the profiling_hooks feature, configures prof:true,prof_active:false, and documents the feature and its jemalloc build scope.
Profiling controls and hook APIs jemalloc-ctl/Cargo.toml, jemalloc-ctl/src/profiling.rs	Adds prof_active, prof_reset, feature-gated hook types and setters, a no-op backtrace hook, and API documentation.
Profiling hook integration validation jemalloc-ctl/src/profiling.rs, jemalloc-ctl/src/macros.rs	Tests sample/free hook activity and backtrace replacement, while skipping the conflicting prof_active generated test when hooks are enabled.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested reviewers: busyjay

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ProfilingModule
  participant Jemalloc
  participant Allocation
  Caller->>ProfilingModule: Install profiling hooks
  ProfilingModule->>Jemalloc: Update experimental hook keys
  Caller->>ProfilingModule: Enable prof_active and reset sampling
  ProfilingModule->>Jemalloc: Update profiling state
  Allocation->>Jemalloc: Allocate or free memory
  Jemalloc->>ProfilingModule: Invoke profiling hooks

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding the profiling_hooks feature and exposing jemalloc's experimental profiling hooks.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

_{Comment @coderabbitai help to get the list of available commands.}

[ti-chi-bot]

Welcome @scottgerring! It looks like this is your first PR to tikv/jemallocator 🎉

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

jemalloc-ctl/src/profiling.rs (1)

286-329: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Consider making the hook setters unsafe fn.

ProfSampleHook/ProfSampleFreeHook/ProfBacktraceHook carry a documented # Safety contract (no unwinding across the FFI boundary, reentrancy constraints) that the compiler cannot verify. Installing a hook that jemalloc will invoke under those constraints is the caller's responsibility, similar to signal-handler registration — conventionally exposed as unsafe fn in Rust. Currently these are safe pub fns, so callers get no compiler nudge to read the safety docs. Since this API is new in this PR, tightening it now avoids a breaking change later.

♻️ Proposed refactor

-pub fn set_prof_sample_hook(
+pub unsafe fn set_prof_sample_hook(
     hook: Option<ProfSampleHook>,
 ) -> crate::error::Result<Option<ProfSampleHook>> {
-    unsafe { crate::raw::update(b"experimental.hooks.prof_sample\0", hook) }
+    crate::raw::update(b"experimental.hooks.prof_sample\0", hook)
 }

(same pattern for set_prof_sample_free_hook and set_prof_backtrace_hook; call sites in hook_tests would need unsafe { ... } wrapping.)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@jemalloc-ctl/src/profiling.rs` around lines 286 - 329, Change
set_prof_sample_hook, set_prof_sample_free_hook, and set_prof_backtrace_hook to
unsafe functions because callers must uphold each hook type’s FFI, unwinding,
and reentrancy safety contract. Update their documentation to expose the
relevant safety requirements and wrap all hook_tests call sites in unsafe blocks
while preserving existing return and error behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@jemalloc-ctl/src/profiling.rs`:
- Around line 167-220: Update the `prof_active` rustdoc to state that jemalloc
initializes it from `opt.prof_active`, distinguishing it from
`thread.prof.active`, which uses `opt.prof_thread_active_init`. Also revise
`prof_reset`’s error documentation to say the `prof:true` default is provided
only by the `profiling_hooks` feature, while `profiling` alone merely enables
profiling support.

---

Nitpick comments:
In `@jemalloc-ctl/src/profiling.rs`:
- Around line 286-329: Change set_prof_sample_hook, set_prof_sample_free_hook,
and set_prof_backtrace_hook to unsafe functions because callers must uphold each
hook type’s FFI, unwinding, and reentrancy safety contract. Update their
documentation to expose the relevant safety requirements and wrap all hook_tests
call sites in unsafe blocks while preserving existing return and error behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 309da892-9803-45d0-aa0e-0ee5b495c73e

📥 Commits

Reviewing files that changed from the base of the PR and between 0e91291 and ff0e303.

📒 Files selected for processing (6)

• jemalloc-ctl/Cargo.toml
• jemalloc-ctl/src/macros.rs
• jemalloc-ctl/src/profiling.rs
• jemalloc-sys/Cargo.toml
• jemalloc-sys/README.md
• jemalloc-sys/build.rs