Profiling

This guide covers the profiling tools available for ethrex developers, including CPU profiling and memory profiling.

CPU Profiling with pprof

Ethrex includes built-in CPU profiling via pprof-rs, gated behind the cpu_profiling feature flag. When enabled, a profiler starts at boot (1000 Hz sampling) and writes a profile.pb file to the current working directory at shutdown.

Prerequisites

To view the generated profiles you need one of:

• Go toolchain (go tool pprof) — the standard pprof viewer
• pprof CLI — standalone binary from google/pprof

Install the standalone CLI:

go install github.com/google/pprof@latest

Building with CPU profiling

# Debug build
cargo build -p ethrex --features cpu_profiling

# Release build (recommended for realistic profiles)
cargo build -p ethrex --release --features cpu_profiling

The cpu_profiling feature is opt-in (not in default) so normal builds are unaffected.

Collecting a profile

1. Start the node as usual:

   ./target/release/ethrex --authrpc.jwtsecret ./secrets/jwt.hex --network holesky
   

   You should see this log line near startup:

   CPU profiling enabled (1000 Hz), will write profile.pb at shutdown
   

2. Let the node run through the workload you want to profile.

3. Stop the node with Ctrl+C or SIGTERM. The file profile.pb will be written to the current working directory and the shutdown logs will include:

   CPU profile written to profile.pb
   

Analyzing the profile

Interactive web UI

go tool pprof -http=:8080 profile.pb

This opens a browser with flame graphs, call graphs, top functions, and source annotations.

Terminal top functions

go tool pprof profile.pb
# then at the (pprof) prompt:
(pprof) top 20
(pprof) top 20 -cum

Flame graph (SVG)

go tool pprof -svg profile.pb > flamegraph.svg

Focus on a specific function

go tool pprof -http=:8080 -focus=execute_block profile.pb

Tips

• Use release builds for profiling. Debug builds have very different performance characteristics due to missing optimizations and extra debug assertions.
• Profile with release-with-debug if you want accurate profiles with full symbol names. This gives optimized code with debug symbols:

  cargo build -p ethrex --profile release-with-debug --features cpu_profiling
  

• Combine with jemalloc — the cpu_profiling feature is orthogonal to jemalloc and jemalloc_profiling. You can enable both:

  cargo build -p ethrex --release --features cpu_profiling,jemalloc
  

• Sampling rate — the profiler samples at 1000 Hz (once per millisecond). This is high enough to get good resolution without significant overhead.
• File location — profile.pb is written to whichever directory you run the binary from. If you want it elsewhere, cd to that directory before starting the node, or move the file after shutdown.

Memory Profiling with jemalloc

Ethrex supports memory profiling through jemalloc, gated behind the jemalloc_profiling feature flag. This enables jemalloc's built-in heap profiling (prof:true) and exposes /debug/pprof/allocs and /debug/pprof/allocs/flamegraph RPC endpoints for on-demand heap dumps.

Building with memory profiling

cargo build -p ethrex --release --features jemalloc_profiling

Note: jemalloc_profiling implies the jemalloc feature, so you don't need to specify both.

External memory profilers

You can also use external tools with the jemalloc feature (without jemalloc_profiling):

Bytehound

Requires Bytehound and jemalloc installed on the system.

cargo build -p ethrex --release --features jemalloc

export MEMORY_PROFILER_LOG=warn
LD_PRELOAD=/path/to/libbytehound.so:/path/to/libjemalloc.so ./target/release/ethrex [ARGS]

Heaptrack (Linux only)

Requires Heaptrack and jemalloc installed on the system.

cargo build -p ethrex --release --features jemalloc

LD_PRELOAD=/path/to/libjemalloc.so heaptrack ./target/release/ethrex [ARGS]
heaptrack_print heaptrack.ethrex.<pid>.gz > heaptrack.stacks

Profiling with Samply

Samply is a sampling CPU profiler that works on macOS and Linux and produces profiles viewable in the Firefox Profiler.

cargo build -p ethrex --profile release-with-debug
samply record ./target/release-with-debug/ethrex [ARGS]

This will open the Firefox Profiler UI in your browser when the process exits.

Feature flags summary