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

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.

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.

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

__register_location

Registers the call site’s structured Location under the identity string used for stats aggregation. file!()/line!()/column!() here resolve to the user’s call site because macro expansion attributes them to the outermost invocation.

axum

Wrap an axum Router so every request it serves is timed and reported in the server section, keyed by matched route (GET /users/{id}).

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 an HTTP 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

AxumLayer

Tower layer that reports per-request response times to the hotpath server worker, bucketed by the axum route template that handled the request.

CountingAllocator

Shared global allocator that tracks allocations when the hotpath-alloc feature is enabled and forwards to the inner allocator unchanged otherwise.

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.

Location

Structured source location of an instrumented call site, captured at compile time by the instrumentation macros.

MeasurementGuardAsync

MeasurementGuardSync

ReqwestHttpMiddleware

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

UreqHttpMiddleware

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

Enums

Format

Output format for profiling reports.

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), where the concrete client type routes to the matching reqwest-middleware wrapper, and for ureq’s ConfigBuilder<AgentScope>, which is returned with the middleware appended.

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.

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; also reads the plain N B form cloud reports carry.

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; also reads the lossless form cloud reports carry (1.004999 ms).

shorten_function_name