🔬 CPU Profiling

Overview

CPU profiling helps you understand where your application spends time. Armature includes built-in profiling support using pprof that generates interactive flamegraphs.

A flamegraph is a visualization where:

• Each box represents a function in the call stack
• The width of a box shows how much CPU time was spent in that function
• Boxes are stacked to show the call hierarchy
• Wider boxes = more time = potential optimization targets

Quick Start

Run the built-in profiling server example:

# Run the profiling server in release mode
cargo run --example profiling_server --release

# In another terminal, generate load
for i in {{1..1000}}; do
  curl -s http://localhost:PORT/tasks > /dev/null
done

# Press Ctrl+C to stop and generate flamegraph
# Open flamegraph-profile.svg in your browser

Adding Profiling to Your App

Add the profiling dependencies to your Cargo.toml:

[dev-dependencies]
pprof = { version = "0.14", features = ["flamegraph", "criterion", "prost-codec"] }
ctrlc = "3.4"

# Enable debug symbols in release for better stack traces
[profile.profiling]
inherits = "release"
debug = true

Reading Flamegraphs

Understanding the flamegraph output:

• X-axis: Stack frames sorted alphabetically (not time order)
• Y-axis: Stack depth (callers below, callees above)
• Width: Percentage of total CPU time
• Color: Random (for visual distinction)

Look for:

• Wide plateaus — Functions using lots of CPU
• Deep stacks — Complex call chains
• Your code — Search for your module names

Optimization Tips