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

  • Profiling hook APIs are now available through the profiling feature, including allocation sampling, deallocation, and backtrace hooks.
  • Added a no-op backtrace hook for disabling backtrace collection.

• Documentation

  • Consolidated profiling hook documentation under the profiling feature.
  • Clarified runtime configuration, hook safety, reset requirements, and backtrace-hook restoration behavior.

• Bug Fixes

  • Corrected profiling test selection and configuration when the profiling feature is enabled.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: d88fde16-7265-449a-b463-69fff201eaec

📥 Commits

Reviewing files that changed from the base of the PR and between d9f07bd and b19340a.

📒 Files selected for processing (1)

• jemalloc-sys/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• jemalloc-sys/README.md

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR exposes profiling hook APIs under the profiling feature, clarifies profiling control behavior, configures hook tests with profiling enabled, and updates feature documentation.

Changes

Profiling controls and hooks

Layer / File(s)	Summary
Runtime profiling controls jemalloc-ctl/src/profiling.rs, jemalloc-sys/README.md	Clarifies prof_active and prof_reset behavior. Documents profiling hooks and runtime configuration under the profiling feature.
Profiling hook API jemalloc-ctl/src/profiling.rs	Makes hook types and setters available under the module’s broader feature configuration. Clarifies hook execution, safety, and backtrace-hook replacement behavior.
Profiling hook validation jemalloc-ctl/src/profiling.rs, jemalloc-ctl/src/macros.rs	Runs hook tests with test-only profiling configuration. Updates test gating and the prof_active test guard.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to b1934

The change exposes profiling controls and hooks without any identified current merge-blocking risk.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ProfilingModule
  participant Jemalloc
  participant Allocation
  Caller->>ProfilingModule: set_prof_sample_hook
  ProfilingModule->>Jemalloc: update profiling hook
  Allocation->>Jemalloc: allocate or free memory
  Jemalloc->>ProfilingModule: invoke profiling hook

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title describes exposing jemalloc profiling hooks, but it incorrectly states that the pull request adds a profiling_hooks feature. The changes move the APIs under the existing profiling featur…	Rename the title to reflect the actual change, for example: Expose jemalloc experimental profiling hooks under the profiling feature.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 3 files. (1 skipped: 1 …
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.

Full details: Title check

Explanation

The title describes exposing jemalloc profiling hooks, but it incorrectly states that the pull request adds a profiling_hooks feature. The changes move the APIs under the existing profiling feature and remove the standalone profiling_hooks feature entry.

• Fix all pre-merge checks with AI

---

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

[scottgerring]

@BusyJay - bump!

[scottgerring]

@BusyJay thanks for taking a look! Comments addressed 💪