Question 1

How to generate flame graphs with perf-map-agent?

Accepted Answer

Use the provided script perf-java-flames with the target PID, and ensure the JVM runs with -XX:+PreserveFramePointer for accurate stack traces. You'll also need to set the FLAMEGRAPH_DIR environment variable to the FlameGraph tools location.

Question 2

perf-map-agent vs AsyncProfiler for Java profiling?

Accepted Answer

perf-map-agent focuses on generating symbol maps for Linux perf tools, enabling system-level integration, while AsyncProfiler is a more self-contained Java profiler with built-in sampling. Choose perf-map-agent if you need to leverage existing perf workflows.

Question 3

Why are Java methods missing in my perf report after using perf-map-agent?

Accepted Answer

This often happens if debug symbols for libjvm.so aren't installed, or if the JVM lacks required flags like -XX:+PreserveFramePointer. Check the README's section on missing symbols and ensure proper agent attachment.

Question 4

How do I attach perf-map-agent to a running Java application?

Accepted Answer

Use the script create-java-perf-map.sh with the process PID, or the AttachOnce runner. The agent attaches dynamically without restarting the JVM, as described in the architecture section.

Question 5

What JVM options give the best results with perf-map-agent?

Accepted Answer

For accurate inlining information, use -XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints. For stack traces, enable -XX:+PreserveFramePointer. These are detailed in the README's known issues and script sections.

Question 6

Can I reload perf-map-agent after making changes?

Accepted Answer

No, the README states that unloading or reloading a changed agent library is unsupported by the JVM; you must restart the target process to use a newer version, which can be disruptive in production.

perf-map-agent

What is perf-map-agent?

Overview

Use Cases

Best For

Related Projects

Found a gem we're missing?

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions