In high-performance Linux software profiling, capturing low-overhead execution traces using perf record is the standard workflow for generating flame graphs, auditing instruction retired counters, and diagnosing CPU cache misses. However, when profiling modern runtime environments that compile bytecode dynamically at runtime—such as Node.js (V8 engine), Java Virtual Machines (JVM with HotSpot), WebAssembly engines, and Just-In-Time (JIT) interpreters—raw performance recordings lack symbol resolution. Because compiled machine code resides in dynamically allocated memory heaps rather than static disk binaries, profiler reports display cryptic hex memory addresses (e.g., 0x7f8b9c412a00) rather than human-readable function names. The perf inject utility bridges this gap by post-processing raw event data, resolving dynamic JIT symbols, correlating instruction traces, and injecting build IDs.
Understanding perf inject Architecture
The Linux perf architecture relies on ELF symbol tables (.symtab and .dynsym) embedded within static binaries and shared libraries to map program counters (IPs) to function names. For JIT engines, code is generated in volatile memory pages:
- JITdump and Perf Maps: Runtimes write dynamic symbol mappings to auxiliary log files (such as
/tmp/perf-PID.maporjit-PID.dump). These logs correlate dynamically allocated memory addresses with method signatures. - Event Stream Transformation:
perf injectoperates as an event filter pipeline. It takes an inputperf.datarecording, reads sideband runtime logs, converts dynamic memory regions into synthetic ELF shared libraries on disk, and outputs a transformedperf.datafile where all addresses point to real symbol entries. - Instruction Trace Decoding: Beyond JIT symbols,
perf injectdecodes hardware trace streams from Intel Processor Trace (Intel PT) or ARM CoreSight, expanding compressed branch packets into synthesised instructions and call-graph events.
Recording JIT Workloads with Sideband Telemetry
To profile a JIT-compiled application, you must configure the language runtime to output symbol dump files while simultaneously capturing CPU cycles with perf record.
Example 1: Profiling Node.js V8 Applications
Node.js includes native support for generating Linux perf JIT dump files via the --perf-prof flag:
# Launch Node.js service with JIT dumping enabled
node --perf-prof app.js &
NODE_PID=$!
# Record performance telemetry for 15 seconds
perf record -k CLOCK_MONOTONIC -F 99 -g -p $NODE_PID -- sleep 15
# Terminate or detach from process
kill -SIGTERM $NODE_PID
This process produces two crucial artifacts: the binary perf.data file and a directory containing jit-*.dump files.
Example 2: Profiling Java JVM Applications
For Java applications running on OpenJDK, attach the perf-map-agent JVMTI library to generate /tmp/perf-PID.map address tables:
# Run JVM application with frame pointer preservation
java -XX:+PreserveFramePointer -jar enterprise-service.jar &
JAVA_PID=$!
# Record stack traces system-wide
perf record -F 99 -g -p $JAVA_PID -- sleep 20
Filtering and Resolving Dynamic Symbols with perf inject
Once the recording concludes, running perf report directly against perf.data will display unresolved hexadecimal pointers for methods compiled dynamically by the JIT engine. To resolve these pointers, process the recording through perf inject.
Injecting JITdump ELF Binaries
Execute perf inject with the --jit flag to parse JIT dumps, generate temporary ELF symbol files, and write an augmented recording:
perf inject --jit -i perf.data -o perf.jitsym.data
During execution, perf inject performs the following operations:
- Locates the corresponding
jit-*.dumpfile referenced in the recording header. - Extracts each compiled bytecode chunk and writes out synthetic ELF binaries (typically under
~/.debug/jit/). - Rewrites the
PERF_RECORD_MMAPevents within the performance stream so that address offsets map directly to the newly synthesized ELF symbols.
Inspecting Resolved Profiles and Generating Flame Graphs
After transforming the data file with perf inject, inspect the resolved call graphs using perf report:
perf report -i perf.jitsym.data --stdio
Instead of anonymous memory addresses, the profile clearly attributes execution overhead to concrete JavaScript functions or Java class methods:
# Samples: 4K of event 'cycles'
# Event count (approx.): 3891482104
#
# Overhead Command Shared Object Symbol
# ........ ....... .................. .....................................
18.42% node jitted-4192-1.so [JIT] processIncomingJsonBuffer
12.15% node jitted-4192-2.so [JIT] parseJwtSignature
8.30% node libnode.so.108 v8::internal::Execution::Call
4.12% node [kernel.kallsyms] [k] copy_user_enhanced_fast_string
To generate an interactive Flame Graph from the resolved dataset:
# Convert resolved perf data to script fold format
perf script -i perf.jitsym.data | stackcollapse-perf.pl > out.folded
# Generate SVG Flame Graph
flamegraph.pl out.folded > node_perf_flamegraph.svg
Decoding Intel Processor Trace (Intel PT) via perf inject
When capturing deterministic execution flows via Intel Processor Trace (intel_pt//u), perf inject is used to decode packet streams into branch trace events:
# Decode hardware Intel PT stream into instruction call events
perf inject --itrace=cb -i perf.data -o perf.decoded.data
# Review branch instruction sequence
perf script -i perf.decoded.data --fields comm,tid,ip,time,sym
Injecting Build IDs for Offline Analysis
When analyzing performance data recorded on production servers across different development machines, inject build IDs into the event stream before transferring the file:
# Inject binary build IDs into recording stream
perf inject -b -i perf.data -o perf.buildid.data
This guarantees that the target analysis workstation can pair the trace with exact debugging symbol packages matching server-side compiler revisions.
By integrating perf inject into systems profiling workflows, software engineers can eliminate unresolved memory stubs, decode hardware trace streams, and accurately diagnose bottlenecks across dynamic JIT runtime environments.