Crate hotpath 

hotpath-rs is a simple async Rust profiler. It instruments functions, channels, futures, and streams to quickly find bottlenecks and focus optimizations where they matter most. It can provide actionable insights into time, memory, and data flow with minimal setup.

Setup & Usage

For a complete setup guide, examples, and advanced configuration, visit hotpath.rs.

Re-exports

pub use json::Route;

Modules

channels

Channel instrumentation module - tracks message flow and channel state.

cpu_baseline

debug

Debug subsystem - value logging, debug logging, and gauges.

functions

Function profiling module - measures execution time and memory allocations per function.

futures

Futures instrumentation module - tracks async Future lifecycle and poll statistics.

hotpath_guard

http

HTTP request instrumentation module - tracks request durations per endpoint.

io

Byte-level I/O instrumentation - tracks read/write/flush/shutdown operations performed through wrapped Read/Write/AsyncRead/AsyncWrite values.

json

JSON serializable types for TUI and CLI consumers.

mutexes

Mutex instrumentation module - tracks lock acquisitions and hold durations.

rw_locks

RwLock instrumentation module - tracks read/write lock acquisitions and hold durations.

sql

SQL query instrumentation module - tracks query execution durations.

streams

Stream instrumentation module - tracks items yielded and stream lifecycle.

threads

This module provides real-time thread monitoring capabilities, collecting CPU usage statistics for all threads in the current process.

wrap

Mirror of std paths so instrumented types can be used as drop-in replacements by prefixing imports with hotpath::wrap:: (e.g. hotpath::wrap::std::sync::RwLock).

Macros

channel

Instrument a channel creation for profiling.

dbg

Debug macro that tracks debug output in the profiler.

future

Instrument a future to inspect future’s lifecycle events.

gauge

Gauge macro for tracking numeric values with set/inc/dec operations.

http

Wrap a reqwest::Client so every request it sends is timed and reported in the http section, keyed by normalized endpoint.

io

Instrument a value implementing std::io::Read, std::io::Write, tokio::io::AsyncRead, or tokio::io::AsyncWrite for byte-level I/O profiling (tokio traits require the tokio feature).

measure_block

Measures the execution time or memory allocations of a code block.

mutex

Instrument an std::sync::Mutex, [parking_lot::Mutex], tokio::sync::Mutex, or async_lock::Mutex for lock wait & acquire profiling.

rw_lock

Instrument an std::sync::RwLock, [parking_lot::RwLock], async_lock::RwLock, or tokio::sync::RwLock for read/write profiling.

stream

Instrument a stream to track its item yields.

tokio_runtime

Initialize Tokio runtime metrics monitoring.

val

Value tracking macro that logs key-value pairs to the profiler.

Structs

CountingAllocator

Shared global allocator that dispatches to enabled allocation tracking features

HotpathGuard

RAII guard that owns the profiler lifetime.

HotpathGuardBuilder

Builder for HotpathGuard - a programmatic alternative to the #[hotpath::main] macro for configuring and initializing the profiler.

MeasurementGuardAsync

MeasurementGuardSync

ReqwestHttpMiddleware

Middleware that reports per-request timing to the hotpath HTTP worker.

Enums

Format

Output format for profiling reports.

OutputDestination

Destination for profiling report output.

ProfilingMode

Profiling mode indicating what type of measurements were collected.

Section

Statics

MAX_LOG_LEN

Traits

InstrumentHttpClient

Wraps an HTTP client so every request it sends is timed and reported. Implemented for reqwest::Client (per enabled reqwest generation); the concrete client type routes to the matching reqwest-middleware wrapper.

IntoF64

Functions

ceil_char_boundary

floor_char_boundary

format_bytes

Formats a byte count into a human-readable string (e.g., “1.5 MB”).

format_count

Formats an allocation count as a string.

format_debug_truncated

format_duration

Formats a duration in nanoseconds into a human-readable string with appropriate units.

format_percentile_header

Formats a percentile value for display as a column header (e.g., "P95", "P99.9").

format_percentile_key

Formats a percentile value for use as a map key (e.g., "p95", "p99.9").

format_rate

Formats an optional per-second rate to one decimal place, or - when absent.

format_throughput

Formats an optional bytes-per-second rate (e.g. 12.4 MB/s), or - when absent. Sub-KB rates keep one decimal place so slow but nonzero traffic doesn’t round down to 0 B/s.

io_unwrap

Consumes an io! wrapper, returning the wrapped value. The escape hatch for calling consuming methods of the wrapped type (e.g. a codec’s finish(self)); borrowing methods are reachable directly through Deref/DerefMut instead.

parse_bytes

Parses a human-readable byte string back to a byte count. Inverse of format_bytes.

parse_count

Parses a count string back to a u64. Inverse of format_count.

parse_duration

Parses a human-readable duration string back to nanoseconds. Inverse of format_duration.

shorten_function_name

Attribute Macros

future_fn

Instruments an async function to track its lifecycle as a Future.

main

Initializes the hotpath profiling system and generates a performance report on program exit.

measure

Instruments a function to measure execution time or memory allocations.

measure_all

Instruments all functions in a module or impl block with the measure profiling macro.

skip

Marks a function to be excluded from profiling when used with measure_all.