Rust性能分析

Getting Started

AI Setup (Recommended)

The quickest way to set up hotpath is to let an AI coding agent do it. Install the hotpath CLI and run init inside your project:

cargo install hotpath --version '^0.25'
hotpath init --agent claude # or --agent codex / --agent opencode

hotpath init downloads the hotpath_init agent skill from GitHub and starts an interactive Claude Code, Codex or OpenCode session with it as setup instructions. The agent inspects your project, adds the feature-gated dependency, instruments main and a starting set of functions, channels and locks, then verifies that everything compiles with profiling enabled and disabled. You review and approve each edit through the agent's regular permission prompts. Requires curl and the claude, codex or opencode CLI on PATH.

You can also use the skill directly, without the hotpath CLI: copy it to ~/.claude/skills/hotpath_init/SKILL.md and run /hotpath_init in a Claude Code session.

Manual installation

Add to your Cargo.toml:

[dependencies]
hotpath = "0.25"

[features]
hotpath = ["hotpath/hotpath"]
hotpath-cpu = ["hotpath/hotpath-cpu"]
hotpath-alloc = ["hotpath/hotpath-alloc"]
hotpath-prometheus = ["hotpath/hotpath-prometheus"]

This config ensures that the lib has no compile time or runtime overhead unless explicitly enabled via a hotpath feature. All the lib dependencies are optional (i.e. not compiled) and all macros are noop unless profiling is enabled.

Basic setup

You'll need only #[hotpath::main] and #[hotpath::measure] macros to get started:

#[hotpath::measure]
fn sync_function(sleep: u64) {
    std::thread::sleep(Duration::from_nanos(sleep));
    let vec1 = vec![1, 2, 3];
    std::hint::black_box(&vec1); // force mem allocation
}

#[hotpath::measure]
async fn async_function(sleep: u64) {
    tokio::time::sleep(Duration::from_nanos(sleep)).await;
}

// When using with tokio, place the #[tokio::main] first
#[tokio::main]
#[hotpath::main]
async fn main() {
    for i in 0..10000 {
        sync_function(i);
        async_function(i * 2).await;

        hotpath::measure_block!("custom_block", {
            std::thread::sleep(Duration::from_nanos(i * 3))
        });
    }
}

Now, run your program with hotpath (and optionally hotpath-alloc features):

cargo run --features='hotpath,hotpath-alloc'

On exit it will print a report with timings, memory allocations and thread usage metrics:

[hotpath] 1.20s | timing, alloc, threads

timing - Function execution time metrics.
+------------------------------+-------+----------+----------+----------+---------+
| Function                     | Calls | Avg      | P95      | Total    | % Total |
+------------------------------+-------+----------+----------+----------+---------+
| docs_example::main           | 1     | 1.20 s   | 1.20 s   | 1.20 s   | 100.00% |
+------------------------------+-------+----------+----------+----------+---------+
| docs_example::async_function | 1000  | 1.15 ms  | 1.20 ms  | 1.15 s   | 96.10%  |
+------------------------------+-------+----------+----------+----------+---------+
| custom_block                 | 1000  | 18.13 µs | 31.71 µs | 18.13 ms | 1.51%   |
+------------------------------+-------+----------+----------+----------+---------+
| docs_example::sync_function  | 1000  | 16.58 µs | 27.63 µs | 16.58 ms | 1.38%   |
+------------------------------+-------+----------+----------+----------+---------+

alloc - Cumulative allocations during each function call (including nested calls).
+------------------------------+-------+---------+---------+---------+---------+
| Function                     | Calls | Avg     | P95     | Total   | % Total |
+------------------------------+-------+---------+---------+---------+---------+
| docs_example::main           | 1     | 63.0 KB | 63.1 KB | 63.0 KB | 100.00% |
+------------------------------+-------+---------+---------+---------+---------+
| docs_example::sync_function  | 1000  | 12 B    | 12 B    | 11.7 KB | 18.58%  |
+------------------------------+-------+---------+---------+---------+---------+
| custom_block                 | 1000  | 0 B     | 0 B     | 0 B     | 0.00%   |
+------------------------------+-------+---------+---------+---------+---------+
| docs_example::async_function | 1000  | 0 B     | 0 B     | 0 B     | 0.00%   |
+------------------------------+-------+---------+---------+---------+---------+

threads - Thread CPU and memory statistics. (RSS: 7.8 MB, Alloc: 2.1 MB, Dealloc: 304.3 KB, Diff: 1.8 MB, 5/10)
+--------------+------+------+----------+----------+----------+
| Thread       | Max% | Avg% | Alloc    | Dealloc  | Diff     |
+--------------+------+------+----------+----------+----------+
| hp-functions | 1.8% | 1.2% | 1.8 MB   | 291.3 KB | 1.5 MB   |
+--------------+------+------+----------+----------+----------+
| main         | 6.3% | 5.1% | 367.8 KB | 9.9 KB   | 357.9 KB |
+--------------+------+------+----------+----------+----------+
| hp-threads   | 0.0% | 0.0% | 10.3 KB  | 3.0 KB   | 7.3 KB   |
+--------------+------+------+----------+----------+----------+
| hp-server    | 0.0% | 0.0% | 1.8 KB   | 56 B     | 1.7 KB   |
+--------------+------+------+----------+----------+----------+
| thread_5     | -    | -    | 640 B    | 24 B     | 616 B    |
+--------------+------+------+----------+----------+----------+