### Install mdBook and plugins Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Install the mdBook dependencies required to build the documentation. Run these commands from the repository root. ```bash cargo install mdbook cargo install mdbook-reading-time cargo install mdbook-assets-hash ``` -------------------------------- ### Install Hotpath Binary with Cargo Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Install the hotpath binary with TUI, hotpath-alloc, and demo features, and the hotpath-samply binary with hotpath feature. ```bash cd /root/hotpath-rs/crates/hotpath/ RUSTFLAGS="--cfg tokio_unstable" cargo install --path . --features='tui,hotpath-alloc,demo' cargo install --path . --bin hotpath-samply --features='hotpath' ``` -------------------------------- ### Deploy Hotpath Binary and Restart tuihost Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Copy the installed hotpath binary to /usr/local/bin and restart the tuihost service. ```bash cp /root/.cargo/bin/hotpath /usr/local/bin/hotpath && sudo systemctl restart tuihost ``` -------------------------------- ### Start PostgreSQL and Redis services with Docker Compose Source: https://github.com/hotpath-rs/hotpath/blob/main/dev_docs/testing.md Copies the sample Docker Compose file and starts the postgres and redis services. Required for service-dependent tests (sql_pg.rs, diesel_pg.rs, toasty_pg.rs, io_redis.rs). ```bash cp docker-compose.yml.sample docker-compose.yml docker compose up -d postgres redis ``` -------------------------------- ### Run tests with cargo test and example Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Run unit tests, binary tests, cloud CLI tests, and an example. Integration tests live in crates/hotpath/tests/ and run one file at a time. ```bash cargo test --lib --features hotpath cargo test -p hotpath --bin hotpath --features=tui cargo test -p hotpath --features cloud --test cloud_cli cargo run -p test-all-features --example all_noop ``` -------------------------------- ### Build and check commands with features Source: https://github.com/hotpath-rs/hotpath/blob/main/AGENTS.md Common cargo commands for building, checking with the TUI feature, and running examples with profiling features. The example commands require the `hotpath` feature and each example lists its exact run command in its top comment. ```bash cargo build # build cargo build --features hotpath # build with profiling enabled cargo check --bin hotpath --features tui # check the TUI binary compiles # Run an example from a test crate (each example lists its exact run command in its top comment) cargo run -p test-tokio-async --example basic --features hotpath cargo run -p test-channels-tokio --example basic_tokio --features hotpath # Profiling modes are combined via features, e.g. cargo run -p test-tokio-async --features='hotpath-alloc' --example basic ``` -------------------------------- ### Install Samply for trace analysis Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Installs the Samply profiler to analyze traces from instrumented benchmarks. ```bash cargo install --locked samply ``` -------------------------------- ### Build and record timing profile with Samply Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Builds the benchmark_noop example with profiling profile and records a Samply trace with 5,000,000 runs. ```bash cargo build --example benchmark_noop --features hotpath --profile profiling && HOTPATH_BENCH_RUNS=5000000 samply record './target/profiling/examples/benchmark_noop' ``` -------------------------------- ### Build and record allocation profile with Samply Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Builds the benchmark_alloc example with hotpath-alloc feature and records a Samply trace. ```bash cargo build --example benchmark_alloc --features='hotpath-alloc' --profile profiling && samply record './target/profiling/examples/benchmark_alloc' ``` -------------------------------- ### Rust example with #[hotpath::main] and #[hotpath::measure] Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/introduction.md Shows the minimal setup for hotpath: annotate functions with #[hotpath::measure] and the main function with #[hotpath::main]. When using tokio, place #[tokio::main] first. The example includes a custom block measured with hotpath::measure_block!. ```rust #[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..1000 { sync_function(i); async_function(i * 2).await; hotpath::measure_block!("custom_block", { std::thread::sleep(Duration::from_nanos(i * 3)) }); } } ``` -------------------------------- ### Launch the hotpath TUI Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/introduction.md Starts the hotpath TUI, which displays timing, memory, and other metrics in real time. Requires the CLI to be installed with auto-instrumentation and demo mode enabled. ```bash hotpath ``` -------------------------------- ### TUI console command with metrics port Source: https://github.com/hotpath-rs/hotpath/blob/main/AGENTS.md Run this in a second terminal after starting a profiled example (metrics server starts on port 6770 by default) to connect the TUI console to that port. ```bash cargo run --bin hotpath --features tui -- console --metrics-port 6770 ``` -------------------------------- ### Install hotpath CLI with auto-instrumentation and demo mode Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/introduction.md Installs the hotpath CLI with the tui, hotpath-alloc, and demo features enabled. Use this to run the TUI in auto-instrumentation mode, where the process profiles itself and displays its own performance metrics in real time. ```bash cargo install hotpath --features='tui,hotpath-alloc,demo' --version '^{{HOTPATH_VERSION}}' ``` -------------------------------- ### Run example with hotpath-cpu flag Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/cpu_profiling.md Run your example with the hotpath-alloc and hotpath-cpu features using the profiling profile. It outputs a CPU usage report in addition to wall-clock time and allocations. ```bash cargo run --features='hotpath-alloc,hotpath-cpu' --profile profiling ``` -------------------------------- ### Example hotpath report output Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/introduction.md Sample output printed on exit, showing timing, allocation, and thread usage metrics. Includes tables for timing, alloc-bytes, and threads. ```text [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 | 1,000 | 1.16 ms | 1.24 ms | 1.16 s | 96.84% | +------------------------------+-------+----------+----------+----------+---------+ | custom_block | 1,000 | 16.86 µs | 29.50 µs | 16.86 ms | 1.41% | +------------------------------+-------+----------+----------+----------+---------+ | docs_example::sync_function | 1,000 | 12.16 µs | 23.84 µs | 12.17 ms | 1.02% | +------------------------------+-------+----------+----------+----------+---------+ alloc-bytes - Exclusive allocation bytes by each function (excluding nested calls). Total: 100.1 KB +------------------------------+-------+---------+---------+---------+---------+ | Function | Calls | Avg | P95 | Total | % Total | +------------------------------+-------+---------+---------+---------+---------+ | docs_example::main | 1 | 88.4 KB | 88.4 KB | 88.4 KB | 88.29% | +------------------------------+-------+---------+---------+---------+---------+ | docs_example::sync_function | 1,000 | 12 B | 12 B | 11.7 KB | 11.71% | +------------------------------+-------+---------+---------+---------+---------+ | custom_block | 1,000 | 0 B | 0 B | 0 B | 0.00% | +------------------------------+-------+---------+---------+---------+---------+ | docs_example::async_function | 1,000 | 0 B | 0 B | 0 B | 0.00% | +------------------------------+-------+---------+---------+---------+---------+ threads - Thread CPU and memory statistics. (Max RSS: 8.6 MB, Alloc: 108.5 KB, Dealloc: 123.8 KB, Diff: -15.3 KB, 4/14) +-----------------+------+------+----------+---------+----------+ | Thread | Max% | Avg% | Alloc | Dealloc | Diff | +-----------------+------+------+----------+---------+----------+ | main | 4.5% | 3.8% | 100.1 KB | 46.0 KB | 54.0 KB | +-----------------+------+------+----------+---------+----------+ | tokio-rt-worker | 0.0% | 0.0% | 79 B | 70.1 KB | -70.0 KB | +-----------------+------+------+----------+---------+----------+ | tokio-rt-worker | 0.0% | 0.0% | 4.2 KB | 471 B | 3.8 KB | +-----------------+------+------+----------+---------+----------+ | tokio-rt-worker | 0.0% | 0.0% | 3.3 KB | 407 B | 2.9 KB | +-----------------+------+------+----------+---------+----------+ ``` -------------------------------- ### Example hotpath report output Source: https://github.com/hotpath-rs/hotpath/blob/main/README.md Example output printed on exit, showing timing, alloc-bytes, and threads sections with tables for each function and thread. ```text [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 | 1,000 | 1.16 ms | 1.24 ms | 1.16 s | 96.84% | +------------------------------+-------+----------+----------+----------+---------+ | custom_block | 1,000 | 16.86 µs | 29.50 µs | 16.86 ms | 1.41% | +------------------------------+-------+----------+----------+----------+---------+ | docs_example::sync_function | 1,000 | 12.16 µs | 23.84 µs | 12.17 ms | 1.02% | +------------------------------+-------+----------+----------+----------+---------+ alloc-bytes - Exclusive allocation bytes by each function (excluding nested calls). Total: 100.1 KB +------------------------------+-------+---------+---------+---------+---------+ | Function | Calls | Avg | P95 | Total | % Total | +------------------------------+-------+---------+---------+---------+---------+ | docs_example::main | 1 | 88.4 KB | 88.4 KB | 88.4 KB | 88.29% | +------------------------------+-------+---------+---------+---------+---------+ | docs_example::sync_function | 1,000 | 12 B | 12 B | 11.7 KB | 11.71% | +------------------------------+-------+---------+---------+---------+---------+ | custom_block | 1,000 | 0 B | 0 B | 0 B | 0.00% | +------------------------------+-------+---------+---------+---------+---------+ | docs_example::async_function | 1,000 | 0 B | 0 B | 0 B | 0.00% | +------------------------------+-------+---------+---------+---------+---------+ threads - Thread CPU and memory statistics. (Max RSS: 8.6 MB, Alloc: 108.5 KB, Dealloc: 123.8 KB, Diff: -15.3 KB, 5/15) +-----------------+------+------+----------+---------+----------+ | Thread | Max% | Avg% | Alloc | Dealloc | Diff | +-----------------+------+------+----------+---------+----------+ | main | 4.5% | 3.8% | 100.1 KB | 46.0 KB | 54.0 KB | +-----------------+------+------+----------+---------+----------+ | tokio-rt-worker | 0.0% | 0.0% | 79 B | 70.1 KB | -70.0 KB | +-----------------+------+------+----------+---------+----------+ | tokio-rt-worker | 0.0% | 0.0% | 4.2 KB | 471 B | 3.8 KB | +-----------------+------+------+----------+---------+----------+ | tokio-rt-worker | 0.0% | 0.0% | 3.3 KB | 407 B | 2.9 KB | +-----------------+------+------+----------+---------+----------+ | hp-functions | 1.3% | 1.0% | 0 B | 2.0 KB | -2.0 KB | +-----------------+------+------+----------+---------+----------+ ``` -------------------------------- ### AI setup prompt for hotpath-cloud Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/cloud.md Paste this prompt into your coding agent inside your project repo. The agent sets up profiling if needed, adds the hotpath-cloud feature, a regression policy, and a GitHub Actions workflow, then runs the benchmark locally to verify the report. ```text Set up hotpath-cloud CI in this Rust project using the instructions at https://hotpath.rs/agent/init_cloud ``` -------------------------------- ### SSH Public Demo Access Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Connect to the public demo server. The username is ignored, so both commands work. ```bash ssh demo.hotpath.rs # or ssh user@demo.hotpath.rs # Both work - username is ignored ``` -------------------------------- ### Install samply Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/cpu_profiling.md Install the samply CPU profiler with cargo. Verify the installed version with `samply --version`; hotpath is tested with version 0.13.x. ```bash cargo install samply --locked ``` ```bash samply --version ``` -------------------------------- ### Create Dedicated Service User Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Create a system user for the tuihost service with no home directory and no login shell. ```bash sudo useradd --system --no-create-home --shell /usr/sbin/nologin tuihost ``` -------------------------------- ### Rollback to Original OpenSSH on Port 22 Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Stops and disables the tuihost service, then enables and starts the original OpenSSH service on port 22. ```bash sudo systemctl stop tuihost sudo systemctl disable tuihost sudo systemctl enable ssh sudo systemctl start ssh ``` -------------------------------- ### Set File Ownership and Permissions Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Secure the tuihost configuration directory and host key by setting ownership and permissions. ```bash sudo chown tuihost:tuihost /etc/tuihost sudo chmod 700 /etc/tuihost sudo chown tuihost:tuihost /etc/tuihost/host_key ``` -------------------------------- ### Install hotpath-samply wrapper binary Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/cpu_profiling.md Install the hotpath-samply wrapper binary that ships with hotpath. Both samply and hotpath-samply must be in PATH at runtime; the host process spawns hotpath-samply, which invokes samply. ```bash cargo install hotpath --bin hotpath-samply --version '^{{HOTPATH_VERSION}}' ``` -------------------------------- ### Run one-liner setup script Source: https://github.com/hotpath-rs/hotpath/blob/main/crates/hotpath/linux-dev/README.md Builds the Docker image, relaxes host sysctls, recreates the container, pre-builds the wrapper, and execs into bash. Run from repo root. Re-run after Docker Desktop VM restart because perf_event_paranoid and kptr_restrict reset. ```bash ./crates/hotpath/linux-dev/setup.sh ``` -------------------------------- ### Fix Missing /run/sshd Directory Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md List the /run/sshd directory and, if missing, create it with proper permissions. ```bash ls -la /run/sshd # If missing: sudo mkdir -p /run/sshd && sudo chmod 755 /run/sshd ``` -------------------------------- ### Service Management Commands Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Check status, view logs, restart the tuihost service, and verify both services are listening on their ports. ```bash # Status sudo systemctl status tuihost sudo systemctl status sshd-admin # Logs sudo journalctl -u tuihost -f # Restart sudo systemctl restart tuihost # Verify both services sudo ss -tlnp | grep -E ':22 |:2222' ``` -------------------------------- ### list_repos Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/mcp_api.md Lists the repositories in your GitHub App installations, each with its benchmarks. Optionally filters to only profiled ones and by name. ```APIDOC ## list_repos ### Description Lists the repositories in your GitHub App installations, each with its benchmarks. Optionally filters to only profiled ones and by name. ### Method MCP tool ### Endpoint list_repos ### Parameters #### Query Parameters - **with_benchmarks** (boolean) - Optional - If true, lists only profiled repositories. - **query** (string) - Optional - Filters repositories by name. ### Response #### Success Response - **repositories** (array) - List of repositories, each with its benchmarks. ``` -------------------------------- ### Install hotpath-rs Agent Skill Source: https://github.com/hotpath-rs/hotpath/blob/main/README.md Run this command to install the reusable hotpath-rs agent skill in a repo that already uses hotpath. The skill maps hotpath tasks to documentation pages so your agent fetches current docs instead of relying on memory. ```bash npx skills add hotpath-rs/hotpath --skill hotpath-rs ``` -------------------------------- ### Install hotpath with TUI feature Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/profiling_modes.md Installs the hotpath CLI with the TUI feature enabled, required for the live dashboard. ```bash cargo install hotpath --features=tui ``` -------------------------------- ### hotpath_build_info metric example Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/prometheus_grafana.md Example scrape output for the hotpath_build_info gauge. The value is always 1; build metadata is stored in labels: hotpath_version, rustc_version, profile, and os. ```text hotpath_build_info{hotpath_version="0.24.0",rustc_version="1.97.0",profile="release",os="linux-x86_64"} 1 ``` -------------------------------- ### Initialize policy file with hotpath cloud init Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/ci_integration.md Installs hotpath with the cloud feature and writes the default policy to hotpath/policy.toml. Every benchmark needs a policy file; an upload without one is refused. ```bash cargo install hotpath --features cloud hotpath cloud init ``` -------------------------------- ### Run byte-level I/O benchmarks for file, TCP, and tokio TCP Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Each benchmark runs both an uninstrumented baseline (raw Read/Write value) and the hotpath::io! wrapped version, printing per-op cost side by side. Iteration counts are fixed per example (200,000 file ops, 10,000 network round trips after a 1,000-op warmup). No external services required. ```bash cargo run -p test-io --example benchmark_file_io --features hotpath --release ``` ```bash cargo run -p test-io --example benchmark_tcp_io --features hotpath --release ``` ```bash cargo run -p test-io --example benchmark_tokio_tcp_io --features hotpath --release ``` -------------------------------- ### Run noop overhead benchmark Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/profiling_overhead.md Runs the benchmark_noop example with the hotpath feature in release mode. The output shows baseline and instrumented per-operation costs; the delta isolates instrumentation overhead. ```bash cargo run --example benchmark_noop --features hotpath --release noop: 100000 calls per mode baseline (raw) 1041.4 ns/op instrumented 1079.9 ns/op (+38.6 ns/op vs baseline) ``` -------------------------------- ### Example output report Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/functions.md Example output showing timing report with function statistics including calls, average, P95, total, and percentage of total execution time. The report also includes a threads section omitted here. ```text [hotpath] 123.86ms | timing, threads timing - Execution duration of functions. +-----------------------+-------+-----------+-----------+-----------+---------+ | Function | Calls | Avg | P95 | Total | % Total | +-----------------------+-------+-----------+-----------+-----------+---------+ | basic::main | 1 | 123.17 ms | 123.21 ms | 123.17 ms | 100.00% | +-----------------------+-------+-----------+-----------+-----------+---------+ | basic::async_function | 100 | 1.16 ms | 1.20 ms | 116.21 ms | 94.35% | +-----------------------+-------+-----------+-----------+-----------+---------+ | basic::sync_function | 100 | 23.55 µs | 42.11 µs | 2.36 ms | 1.91% | +-----------------------+-------+-----------+-----------+-----------+---------+ | custom_block | 100 | 23.52 µs | 36.51 µs | 2.35 ms | 1.91% | +-----------------------+-------+-----------+-----------+-----------+---------+ ``` -------------------------------- ### Check Enabled Services Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Verify which services are enabled at boot. Expected output: tuihost and sshd-admin are enabled, sshd is disabled. ```bash sudo systemctl is-enabled tuihost # enabled sudo systemctl is-enabled sshd-admin # enabled sudo systemctl is-enabled sshd # disabled ``` -------------------------------- ### Pin Valgrind version in GitHub Actions for ARM64 Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/callgrind.md GitHub Actions workflow step that installs the patched Valgrind fork on ARM64 runners using hotpath-rs/setup-valgrind, pinning the action and version. ARM64 support is experimental and counts may be invalid. ```yaml runs-on: ubuntu-26.04-arm steps: - uses: hotpath-rs/setup-valgrind@v1.1.0 with: version: 3.28.0.hotpath-rs-2 ``` -------------------------------- ### tmpfiles.d Configuration for /run/sshd Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Create a tmpfiles.d configuration to ensure /run/sshd exists with correct permissions, required by OpenSSH for privilege separation. ```plaintext d /run/sshd 0755 root root - ``` -------------------------------- ### Run SQL benchmarks for sqlx, diesel, toasty (PostgreSQL) Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Each command runs same point lookup against real PostgreSQL server, so every op includes TCP round trip - closer to production numbers, but round trip dominates and deltas below ~1µs are within run-to-run noise. Iteration count defaults to 10,000. Start database first with 'docker compose up -d postgres'. Requires --features hotpath; diesel also needs pg feature. ```bash cargo run -p test-sqlx-08 --example benchmark_sql_sqlx_postgres --features hotpath --release ``` ```bash cargo run -p test-diesel --example benchmark_sql_diesel_postgres --features hotpath,pg --release ``` ```bash cargo run --manifest-path crates/test-toasty/Cargo.toml --example benchmark_sql_toasty_postgres --features hotpath --release ``` -------------------------------- ### Run integration tests individually Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Run integration tests one file at a time with --nocapture and --test-threads=1. Examples include functions_timing and prometheus_metrics. ```bash cargo test --features hotpath --test functions_timing -- --nocapture --test-threads=1 cargo test --features hotpath-prometheus --test prometheus_metrics -- --nocapture --test-threads=1 ``` -------------------------------- ### Pass explicit handle to tokio_runtime! Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/tokio_runtime.md Use an explicit handle when not inside a Tokio context to start the background metrics sampler. ```rust let handle = tokio::runtime::Handle::current(); hotpath::tokio_runtime!(&handle); ``` -------------------------------- ### SSH demo of hotpath-rs TUI Source: https://github.com/hotpath-rs/hotpath/blob/main/README.md Connect to the hotpath-rs TUI demo via SSH without installing anything. ```bash ssh demo.hotpath.rs ``` -------------------------------- ### Call tokio_runtime! inside async main Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/tokio_runtime.md Invoke the macro inside an async main to start background sampling of Tokio runtime metrics. ```rust #[tokio::main] #[hotpath::main] async fn main() { hotpath::tokio_runtime!(); // ... } ``` -------------------------------- ### macOS: grant samply profiling permissions Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/cpu_profiling.md Run `samply setup` on macOS to sign the samply binary so it can attach to a running process by PID. ```bash samply setup ``` -------------------------------- ### Run SQL benchmarks for sqlx, diesel, toasty (in-memory SQLite) Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Each command runs both uninstrumented baseline and instrumented version, hammering same point lookup against in-memory SQLite. Delta isolates per-query instrumentation overhead (tracing dispatch, normalization keying, event enqueue). sqlx and Toasty baselines run before hotpath tracing layer installed; Diesel baseline uses connection before instrument_diesel_sql() called. Iteration count defaults to 50,000 (HOTPATH_BENCH_RUNS). Requires --features hotpath. ```bash cargo run -p test-sqlx-08 --example benchmark_sql_sqlx --features hotpath --release ``` ```bash cargo run -p test-diesel --example benchmark_sql_diesel --features hotpath --release ``` ```bash cargo run --manifest-path crates/test-toasty/Cargo.toml --example benchmark_sql_toasty --features hotpath --release ``` -------------------------------- ### Run event transport benchmarks (throughput and Criterion) Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Runs one lockstep scenario with hotpath-meta profiling the queue: once through the throughput example, five times through the Criterion benchmark. The hot path is a plain slot store plus one Release publish, with no mutex or RMW atomic. ```bash cargo run -p hotpath-drain --example throughput --release --features hotpath-alloc-meta ``` ```bash HOTPATH_META_CRITERION_ITERATIONS=5 cargo bench -p test-drain-criterion --bench drain --features hotpath-alloc-meta -- --test --exact drain/lockstep ``` -------------------------------- ### Set [functions.icount] for merged benchmark Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/agent/init_cloud.md Conservative starting point for instruction-count judging in the policy file used by a new merged benchmark. Add the section if missing; keep other sections unchanged. ```toml [functions.icount] judged = true fail_check = false min_percent_change = 3 metrics = ["avg", "total"] min_calls = 1 ``` -------------------------------- ### hotpath-wrapper.sh script Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Wrapper script for tuihost that picks a random metrics port per connection and runs the hotpath console. Sets HOTPATH_METRICS_PORT and disables samply load and hints. Executes /usr/local/bin/hotpath console with the chosen port. ```bash #!/bin/bash # Wrapper for tuihost: picks a random metrics port and runs hotpath console PORT=$((RANDOM % 16384 + 49152)) export HOTPATH_METRICS_PORT="$PORT" export HOTPATH_DISABLE_SAMPLY_LOAD=1 export HOTPATH_DISABLE_HINTS=1 export HOTPATH_DISABLE_TUI_HINTS=1 export HOTPATH_SAMPLY_WRAPPER_BIN="/root/.cargo/bin/samply" export HOTPATH_SAMPLY_BIN="/root/.cargo/bin/hotpath-samply" exec /usr/local/bin/hotpath console --metrics-port "$PORT" ``` -------------------------------- ### Example icount report output Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/callgrind.md Sample output of the icount report showing inclusive instruction counts per function, with total and percentage columns. This report replaces the timing report under Valgrind. ```text icount - Inclusive instructions executed per function (Callgrind Ir). Total: 39,730,412 +------------------------------+-------+-----------+------------+---------+ | Function | Calls | Avg | Total | % Total | +------------------------------+-------+-----------+------------+---------+ | instructions::recursive | 4 | 4,500,564 | 18,002,258 | 45.31% | +------------------------------+-------+-----------+------------+---------+ | instructions::async_fn | 2 | 7,200,797 | 14,401,595 | 36.25% | +------------------------------+-------+-----------+------------+---------+ | instructions::free_fn | 2 | 1,800,012 | 3,600,024 | 9.06% | +------------------------------+-------+-----------+------------+---------+ ``` -------------------------------- ### Run profiled app (Terminal 1) Source: https://github.com/hotpath-rs/hotpath/blob/main/dev_docs/tui.md Starts a profiled app with the metrics server on port 6770. Use in the first terminal of the two-terminal workflow. ```bash cargo run -p test-tokio-async --example long_running --features hotpath ``` -------------------------------- ### Run CPU smoke test Source: https://github.com/hotpath-rs/hotpath/blob/main/crates/hotpath/linux-dev/README.md Builds the hotpath-samply wrapper and runs the cpu_basic example with hotpath-cpu. A working run prints both the timing table and a functions-cpu table attributing samples to heavy_work / light_work. ```bash docker exec -it hotpath-linux bash -lc ' cargo build -p hotpath --bin hotpath-samply --features hotpath-cpu --profile profiling && HOTPATH_SAMPLY_WRAPPER_BIN=/work/target-linux/profiling/hotpath-samply \ cargo run -p test-tokio-async --example cpu_basic \ --features "hotpath-cpu" --profile profiling ' ``` -------------------------------- ### Run with hotpath-alloc feature to profile memory allocations Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/faq.md Enable the `hotpath-alloc` feature to install a tracking global allocator and report allocation counts and bytes for every instrumented function. Async functions are measured per poll, so allocations are attributed correctly even when a future moves between Tokio worker threads. ```bash cargo run --features='hotpath-alloc' ``` -------------------------------- ### Check tuihost Logs and Port 22 Usage Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md View the last 50 journal entries for tuihost and check if port 22 is in use. ```bash sudo journalctl -u tuihost -n 50 # Check if port 22 is in use: sudo ss -tlnp | grep :22 ``` -------------------------------- ### Run Redis I/O benchmark Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Sends raw RESP PING/SET/GET round trips over a plain vs instrumented TcpStream to a real server. Start the database first with `docker compose up -d redis` (host port 6390); the benchmark skips when nothing listens there. ```bash cargo run -p test-io --example benchmark_redis_io --features hotpath --release ``` -------------------------------- ### Just recipes for tests and docs Source: https://github.com/hotpath-rs/hotpath/blob/main/AGENTS.md Just commands to run all integration tests and serve the mdbook docs locally with live reload at http://localhost:3000. ```bash just test_all # Run all integration tests just docs # Serve the mdbook docs locally with live reload (http://localhost:3000) ``` -------------------------------- ### hotpath cloud auth --pretty JSON output Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/agents_cli.md Example JSON response from hotpath cloud auth --pretty showing the login and token details. ```json { "login": "pawurb", "token": { "name": "laptop", "expires_at": "2026-12-25T11:27:12.311073Z" } } ``` -------------------------------- ### Install Diesel SQL instrumentation before opening connections Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/sql_tracing.md Registers instrumentation as the default for newly-established connections. Connections established before the call are not instrumented. Synchronous connections only; diesel_async support is coming soon. ```rust hotpath::instrument_diesel_sql(); // open connections AFTER this call so they pick up the instrumentation let mut conn = SqliteConnection::establish(":memory:")?; // or any other Diesel backend: let mut conn = PgConnection::establish(&database_url)?; ``` -------------------------------- ### Add label to endpoint keys Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/http_tracing.md Optional label prefixes every endpoint key produced by the client. Example output: "github: GET api.github.com/repos/{id}". ```rust let github = hotpath::http!(reqwest::Client::new(), label = "github"); // -> "github: GET api.github.com/repos/{id}" ``` -------------------------------- ### CPU usage report output Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/cpu_profiling.md Example output of the CPU usage report showing per-function samples and percentages. The displayed samply load command opens an interactive performance report. ```text +------------------------+-----------+---------+ | Function | Samples | % Total | +------------------------+-----------+---------+ | cpu_basic::sync_work | 1,915,914 | 56.13% | +------------------------+-----------+---------+ | cpu_basic::async_sleep | 14,056 | 0.41% | +------------------------+-----------+---------+ | cpu_basic::sync_alloc | 1,581 | 0.05% | +------------------------+-----------+---------+ samply load /tmp/hotpath/61089-1778083683167502000/hp.json.gz ``` -------------------------------- ### Run MCP server with custom configuration Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/mcp.md Starts the MCP server with a custom port and authentication token using environment variables. The default port is 6771 and the token is optional. ```bash HOTPATH_MCP_PORT=8080 HOTPATH_MCP_AUTH_TOKEN=secret123 \ cargo run --features='hotpath-mcp' ``` -------------------------------- ### Install function sink with hotpath::set_function_sink Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/functions.md Installs a callback that sees every #[measure] and measure_block! scope as it runs. Both enter and exit run inline on the instrumented thread, so keep them cheap and non-blocking. Only one sink can be installed per process; a second call returns FunctionSinkAlreadySet. Scopes filtered by HOTPATH_FOCUS or entered before installation are not reported. ```rust use std::sync::atomic::{AtomicU64, Ordering}; use hotpath::{FunctionSink, ScopeKind}; #[derive(Default)] struct Timeline { next: AtomicU64, } impl FunctionSink for Timeline { fn enter(&self, name: &'static str, kind: ScopeKind) -> u64 { // record the start of `name` self.next.fetch_add(1, Ordering::Relaxed) } fn exit(&self, name: &'static str, kind: ScopeKind, token: u64) { // record the end of the scope started by `token` } } #[hotpath::main] fn main() { hotpath::set_function_sink(Timeline::default()).unwrap(); // ... } ``` -------------------------------- ### SQL normalization example: IN list collapse Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/sql_tracing.md Two parameterized executions of the same statement are normalized to a single bucket. Single-quoted literals, positional placeholders, numeric literals, and runs of '?' in IN lists are replaced with '?', and whitespace is squashed. ```sql SELECT * FROM users WHERE id IN (1, 2, 3) ``` ```sql SELECT * FROM users WHERE id IN (4, 5, 6, 7, 8) ``` -------------------------------- ### tuihost systemd service file Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Systemd unit for the tuihost SSH server on port 22. Runs as user tuihost, binds to privileged port 22 with CAP_NET_BIND_SERVICE, and enforces resource limits (MemoryMax=2G, CPUQuota=200%, TasksMax=4096) and sandboxing. One session uses ~35M RSS, ~60 threads, ~35 fds. ```ini [Unit] Description=TUI SSH Host for Hotpath Console After=network.target [Service] Type=simple User=tuihost Group=tuihost ExecStart=/usr/local/bin/tuihost -l 0.0.0.0:22 -k /etc/tuihost/host_key -c /usr/local/bin/hotpath-wrapper.sh -e HOTPATH_EXCLUDE_WRAPPER=true -e HOTPATH_FUNCTIONS_LIMIT=15 --max-connections 100 --timeout 600 --max-session-duration 600 Environment=NO_COLOR=1 Restart=always RestartSec=5 # Resource ceilings (one session is ~35M RSS, ~60 threads, ~35 fds) MemoryHigh=1536M MemoryMax=2G MemorySwapMax=0 OOMPolicy=continue CPUQuota=200% TasksMax=4096 LimitNOFILE=65536 # Sandboxing NoNewPrivileges=yes ProtectSystem=strict ProtectHome=yes PrivateTmp=yes PrivateDevices=yes ProtectKernelTunables=yes ProtectControlGroups=yes RestrictNamespaces=yes RestrictRealtime=yes RestrictSUIDSGID=yes # Allow binding to privileged port 22 AmbientCapabilities=CAP_NET_BIND_SERVICE CapabilityBoundingSet=CAP_NET_BIND_SERVICE [Install] WantedBy=multi-user.target ``` -------------------------------- ### Cargo.toml setup for hotpath Criterion adapter Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/criterion.md Add hotpath as a dev-dependency with the criterion-0-8 feature (or criterion-0-5/0-6/0-7 for those versions) and forward hotpath's profiling features. The [dependencies] entry is used by #[hotpath::measure] in library code and is a no-op without profiling features; the [dev-dependencies] entry adds the Criterion adapter only to benchmark, test, and example builds. A project that only uses hotpath from benchmarks can drop the [dependencies] entry. ```toml [dependencies] hotpath = "{{HOTPATH_VERSION}}" [dev-dependencies] criterion = "0.8" hotpath = { version = "{{HOTPATH_VERSION}}", features = ["criterion-0-8"] } [features] hotpath = ["hotpath/hotpath"] hotpath-alloc = ["hotpath", "hotpath/hotpath-alloc"] hotpath-callgrind = ["hotpath", "hotpath/hotpath-callgrind"] hotpath-cloud = ["hotpath", "hotpath/hotpath-cloud"] ``` -------------------------------- ### Run program with MCP enabled alongside profiling Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/mcp.md Use this command to run your Rust program with the hotpath-alloc and hotpath-mcp features enabled, which starts the MCP server inside your application to serve live performance data to LLM agents. ```bash cargo run --features='hotpath-alloc,hotpath-mcp' ``` -------------------------------- ### AI setup prompt for building a hotpath Grafana dashboard Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/prometheus_grafana.md Paste this prompt into an AI coding agent inside the project repo to generate a dashboard JSON file with panels for instrumented subsystems. The agent only writes the dashboard; configure the metrics endpoint and Prometheus scrape job separately, then import the file into Grafana. ```text Build a hotpath Grafana dashboard for this Rust project using the instructions at https://hotpath.rs/agent/init_grafana ``` -------------------------------- ### Install hotpath with cloud feature Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/agents_cli.md Install the hotpath CLI with the cloud feature using Cargo. ```bash cargo install hotpath --features cloud ``` -------------------------------- ### Run with hotpath-prometheus feature Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/prometheus_grafana.md Starts the application with the hotpath-prometheus feature enabled. The exporter starts automatically with the profiler on 127.0.0.1:6772, customizable via HOTPATH_PROMETHEUS_PORT and HOTPATH_PROMETHEUS_HOST. ```bash cargo run --features='hotpath-prometheus' ``` -------------------------------- ### Build and run merged native/Callgrind benchmark Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/callgrind.md Builds the benchmark with hotpath-alloc, hotpath-cloud, and hotpath-callgrind features, then runs it natively with a JSON report, and again under Callgrind with HOTPATH_MERGE_REPORT pointing to the native report. Requires hotpath 0.30.0 or newer and both hotpath-callgrind and hotpath-cloud features. ```bash cargo build --release --example my_benchmark --features hotpath-alloc,hotpath-cloud,hotpath-callgrind HOTPATH_OUTPUT_FORMAT=json HOTPATH_OUTPUT_PATH=native.json \ target/release/examples/my_benchmark HOTPATH_OUTPUT_FORMAT=json HOTPATH_OUTPUT_PATH=merged.json \ HOTPATH_MERGE_REPORT=native.json \ valgrind -q --tool=callgrind --instr-atstart=no \ target/release/examples/my_benchmark ``` -------------------------------- ### ARM64 runner job configuration with patched Valgrind Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/ci_integration.md Use for merged profiling mode on ARM64 Linux runners. Requires hotpath 0.31.0+ and the patched Valgrind from hotpath-rs/setup-valgrind; otherwise uploads are rejected. Replaces the standard 'Install valgrind' apt step in every benchmark job. ```yaml runs-on: ubuntu-26.04-arm env: HOTPATH_USER_METADATA: runner=Linux-ARM64,toolchain=1.99.0,profile=release,valgrind=3.28.0.hotpath-rs-2 steps: # replaces the `Install valgrind` apt step - uses: hotpath-rs/setup-valgrind@v1.1.0 with: version: 3.28.0.hotpath-rs-2 ``` -------------------------------- ### Start persistent container Source: https://github.com/hotpath-rs/hotpath/blob/main/crates/hotpath/linux-dev/README.md Starts a detached container named hotpath-linux with required capabilities and environment. CARGO_TARGET_DIR keeps container builds separate from host target/. ```bash docker run -d --name hotpath-linux \ --cap-add=SYS_PTRACE --cap-add=PERFMON \ --security-opt seccomp=unconfined \ -v "$PWD":/work -w /work \ -e CARGO_TARGET_DIR=/work/target-linux \ hotpath-linux sleep infinity ``` -------------------------------- ### Paginate reports with cursor Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/agents_cli.md Passes the `next_cursor` value as `--cursor` with the same filters to get the next page. Each run prints one page of `--limit N` reports (1 to 50, default 20). A listing always exits `0`, even when empty or containing regressed/failed reports. ```bash hotpath cloud reports --repo hotpath-rs/hotpath --benchmark drain --limit 20 --cursor "AQGhrfsKdXRql69bTVi8KXc" ``` -------------------------------- ### Fetch hotpath documentation as markdown Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/agent/setup.md Use this curl command to retrieve any hotpath documentation page as markdown. The server requires the Accept header; a #fragment is not sent, so fetch the whole page and find the heading. ```bash curl -fsSL -H 'Accept: text/markdown' https://hotpath.rs/functions ``` -------------------------------- ### Max queue size since start by channel Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/agent/init_grafana.md PromQL query for max queue size since start; the capacity is in the type label. A queue at capacity means consumers are not keeping up. Group by source, label, iter, type, payload. ```promql sort_desc(topk(10, max by (source, label, iter, type, payload) (hotpath_channel_max_queue_size))) ``` -------------------------------- ### Run futures and streams benchmarks Source: https://github.com/hotpath-rs/hotpath/blob/main/CONTRIBUTING.md Runs benchmarks for futures and streams, each comparing baseline and hotpath::io! wrapped versions. ```bash cargo run -p test-futures --example benchmark_future --features hotpath --release ``` ```bash cargo run -p test-streams --example benchmark_stream --features hotpath --release ``` -------------------------------- ### GET /auth Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/src/mcp_api.md Returns the user and token associated with the request. Requires a personal API token in the Authorization header. ```APIDOC ## GET /auth ### Description Returns the user and token of the request. ### Method GET ### Endpoint https://hotpath.rs/api/v1/auth ### Response #### Success Response (200) - **login** (string) - The user's login. - **token** (object) - The token details. - **name** (string) - The token name. - **expires_at** (string) - The token expiration timestamp. #### Request Example ```bash curl -H "Authorization: Bearer $HOTPATH_API_TOKEN" https://hotpath.rs/api/v1/auth ``` #### Response Example ```json {"login":"pawurb","token":{"name":"laptop","expires_at":"2026-12-25T11:27:12.311073Z"}} ``` ``` -------------------------------- ### SSH Admin Access on Port 2222 Source: https://github.com/hotpath-rs/hotpath/blob/main/docs/ssh_demo.md Connect to the admin interface on port 2222 as root. ```bash ssh -p 2222 root@demo.hotpath.rs ```