Hotpath Init
Developmenthotpath_initHotpath Init is an Agent Skill for development published in the pawurb/hotpath-rs repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Configure hotpath profiling in a Rust project. Adds the hotpath dependency with feature-gated setup, instruments main with
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/pawurb/hotpath-rs/blob/HEAD/skills/hotpath_init/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/hotpath-init, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Initialize hotpath Profiling
Set up hotpath profiling in the current Rust project. The setup is fully feature-gated: zero compile-time and runtime overhead unless the hotpath feature is explicitly enabled. All macros are noops when the feature is off, so no cfg_attr wrapping is needed.
Steps
1. Inspect the project
- Find the binary crate(s) and the
mainfunction. If there is nomainyou control (e.g. a library or a test harness), use theHotpathGuardBuilderAPI instead of#[hotpath::main](see step 3). - Detect the async runtime (
tokio,smol, none) and which instrumentable primitives the code uses: channels (tokio::sync::mpsc/oneshot,std::sync::mpsc,crossbeam_channel,futures_channel),std::sync::Mutex,RwLock(std/parking_lot/tokio/async-lock), futures streams, sqlx.
2. Add the dependency and feature passthrough
In the target crate's Cargo.toml:
[dependencies]
hotpath = "0.21"
[features]
hotpath = ["hotpath/hotpath"]
hotpath-alloc = ["hotpath/hotpath-alloc"]
Enable extra hotpath cargo features on the dependency based on what the project uses:
tokio- fortokio::syncchannel instrumentation andhotpath::tokio_runtime!()metrics:hotpath = { version = "0.21", features = ["tokio"] }crossbeam- forcrossbeam_channelinstrumentationfutures- forfutures_channelinstrumentationsqlx- for SQL query profiling viahotpath::sqlx_tracing_layer()
If the crate already has a [features] section, merge the entries; don't clobber it.
3. Instrument main
#[hotpath::main] initializes the profiler and prints the report when main exits. With tokio, #[tokio::main] must come FIRST (above):
#[tokio::main]
#[hotpath::main]
async fn main() {
// ...
}
Optional parameters: #[hotpath::main(percentiles = [50, 95, 99.9], format = "json", limit = 20)]. Defaults are fine for a first setup; don't add parameters unless asked.
If attribute placement on main is not possible, build a guard programmatically (report prints when the guard drops):
let _hotpath = hotpath::HotpathGuardBuilder::new("main")
.percentiles(&[50.0, 95.0, 99.9])
.build();
4. Instrument functions
- Prefer
#[hotpath::measure_all]on inline modules andimplblocks - it instruments every function inside. Exclude noisy or trivial functions with#[hotpath::skip]. - Use
#[hotpath::measure]on individual functions, both sync and async. - Useful parameters:
log = true(log return values, requiresDebug),label = "name"(custom identifier, duplicates panic at runtime). Applylog = trueonly ifDebugis already implemented. hotpath::measure_block!("label", { ... })for ad-hoc code blocks.
Start with hot paths: request handlers, worker loops, parsing/serialization, IO-heavy functions. Don't instrument one-line getters.
Async functions are measured runtime-agnostically, and under hotpath-alloc their allocations are tracked too (per-poll attribution via an async bridge), so no special handling is needed.
5. Wrap data-flow primitives
Wrap at the creation site; all wrappers accept optional label = "name" and (where noted) log = true:
// Channels (tokio mpsc/oneshot, std mpsc, crossbeam, futures_channel)
let (tx, rx) = hotpath::channel!(mpsc::channel::<String>(100), label = "jobs", log = true);
// futures_channel bounded requires proxy mode and explicit capacity:
let (tx, rx) = hotpath::channel!(mpsc::channel::<String>(10), proxy = true, capacity = 10);
// Locks (wait time + held time)
let mutex = hotpath::mutex!(std::sync::Mutex::new(state), label = "state");
let lock = hotpath::rw_lock!(tokio::sync::RwLock::new(config), label = "config");
// Streams and futures
let s = hotpath::stream!(stream::iter(1..=10), label = "events");
let result = hotpath::future!(some_async_operation(), label = "fetch").await;
Wrapped locks/channels are drop-in: the wrappers expose the same API, so call sites don't change. If passing them across function boundaries requires type-signature changes, note that to the user rather than rewriting half the codebase silently.
Wrapper macros return types prefixed with hotpath::wrap, make sure to update type signatures where needed. Explain to user that these types are no-op unless hotpath feature is enabled.
Apply log = true only if Debug is already implemented.
6. Optional extras (only when relevant)
- Tokio runtime metrics: call
hotpath::tokio_runtime!();once at startup (requirestokiofeature). - SQL profiling (sqlx 0.8/0.9): add the layer to the tracing subscriber once -
tracing_subscriber::registry().with(hotpath::sqlx_tracing_layer()).init();(requiressqlxfeature). Don't filter out thesqlx::querytarget.
7. Verify
cargo check # feature off: must still compile, zero overhead
cargo check --features hotpath # feature on
cargo run --features hotpath # prints report on exit
Optionally verify alloc mode: cargo run --features 'hotpath,hotpath-alloc'.
Report what was instrumented and mention next steps: the live TUI (cargo install hotpath --features tui, then hotpath console while the app runs - metrics server listens on port 6770 by default), HOTPATH_REPORT=all for all report sections, and HOTPATH_OUTPUT_FORMAT=json for machine-readable output.
Also explain to the user that hotpath is safe to keep as a regular (non-optional) dependency: unless the hotpath feature is enabled, it compiles zero third-party dependencies (only the hotpath crates themselves), and all macros expand to noops, so there is no compile-time bloat and no runtime overhead.
Rules
- Never enable the
hotpathfeature by default (default = []); profiling must stay opt-in. - Keep edits minimal: dependency, main, and a sensible starting set of instrumented functions/primitives. Expand coverage only when the user asks.