AP-Agent

Async Profiler Agent is a minimal Java agent that allows you to proxy to Async Profiler via a minimal REST API, making it easy to profile your applications. Simply add it to the start of the JVM and as it uses the AP-Loader, there is no need for Async Profiler up front.

Usage

Download the latest version.

To use the AP-Agent, simply add it to the JVM startup. The agent exposes a REST API for profiling with the following endpoint: http://localhost:8080/profiler/profile.

java -javaagent:/path/to/ap-agent.jar -jar /path/to/my-awesome-app.jar

The endpoint accepts the following parameters:

event: The type of event to profile (e.g. cpu, itimer, wall)
output: The desired output format (e.g. flamegraph, hotcold, jfr, pprof, fp)
duration: The length of time to profile for (in seconds)

Flame Graph

For example, to profile CPU usage for 30 seconds and output the results in Flamegraph format, the following API call would be used: http://localhost:8080/profiler/profile?event=cpu&output=flame&duration=30

Hot/Cold Flame Graph

This type of visualization combines both on-CPU and off-CPU flame graphs. This visualization provides a comprehensive view of the performance data by showing all thread time in one graph and allowing direct comparisons between on-CPU and off-CPU code path durations.

For example, the following API call would be used: http://localhost:8080/profiler/profile?event=cpu&output=hotcold&duration=30

Continuous Profiling a la Bash

We can create a simple bash script to continuously profile our application and output the results to a file.

#!/bin/bash

event=${1:-itimer}
profiling_duration=${2:-30}
results_folder=${3:-profiling_results}

mkdir -p $results_folder

while true; do
    timestamp=$(date +%Y-%m-%d_%H-%M-%S)
    output_file="${event}_profile_$timestamp.html"
    start_time=$(date +%s)
    curl -s "http://localhost:8080/profiler/profile?event=$event&output=flame&duration=$profiling_duration" -o "$results_folder/$output_file"
    end_time=$(date +%s)
    duration=$((end_time - start_time))
    echo "Profile saved to $results_folder/$output_file at $(date) took $duration seconds."
done

Running the script with the cpu event and 60 second duration, we can see the results in the profiling_results folder.

./loop.sh cpu 60 profiling_results

Profile saved to profiling_results/cpu_profile_2023-01-24_16-16-24.html at 04:17:24 took 60 seconds.
Profile saved to profiling_results/cpu_profile_2023-01-24_16-16-24.html at 04:18:24 took 60 seconds.

Examples

Basic example with curl
Example using jfrtofp-server
Example using the loop.sh script

Basic example with `curl`

Execute the profiler for the cpu event, fp (Firefox Profiler) output, a 60 seconds duration and write the response to profiling_results/firefox-profiler-example.json.gz

curl -s "http://localhost:8080/profiler/profile?event=cpu&output=fp&duration=60" -o profiling_results/firefox-profiler-example.json.gz

Visit the Firefox Profiler page

Load the output file from step 1, and you'll see the profiling result

Example using `jfrtofp-server`

Execute the profiler for the cpu event, fp (Firefox Profiler) output, a 60 seconds duration and write the response to profiling_results/firefox-profiler-example.json.gz

curl -s "http://localhost:8080/profiler/profile?event=cpu&output=fp&duration=60" -o profiling_results/firefox-profiler-example.json.gz

Start the jfrtofp-server, you can follow the steps from the README, with the output file from step 1 as an argument

java -jar jfrtofp-server-all.jar profiling_results/firefox-profiler-example.json.gz

The jfrtofp-server will log a message like Navigate to http://localhost:55287/from-url/http%3A%2F%2Flocalhost%3A55287%2Ffiles%firefox-profiler-example.json.gz to launch the profiler view
Just click that link, and you will see the profiling result in the Firefox Profiler page

Example using the `loop.sh` script

Continuously profile the application for the cpu event, fp (Firefox Profiler) output, a 60 seconds duration and write the execution results to profiling_results/ folder

./loop.sh cpu 60 profiling_results fp

Profile saved to profiling_results/cpu_profile_2023-01-24_16-16-24.json.gz at 04:17:24 took 60 seconds.
Profile saved to profiling_results/cpu_profile_2023-01-24_16-16-24.json.gz at 04:18:24 took 60 seconds.

Visit the Firefox Profiler page
Load the output file from step 1, and you'll see the profiling result

Profiling results

Call tree

Flame graph

Go Mode

The agent also supports a GO(lang) mode, which exposes the /debug/pprof/profile endpoint. This is where we can use the go pprof tools.

java -Dap-agent.handler.go-mode=true -javaagent:/path/to/ap-agent.jar -jar /path/to/my-awesome-app.jar

go tool pprof -http :8000 http://localhost:8080/debug/pprof/profile?seconds=30

TODO

Add support for Context ID

License

This code base is available ander the Apache License, version 2.

fggarcia/ap-agent