<dependency>
<groupId>me.bechberger</groupId>
<artifactId>ap-loader-all</artifactId>
<version>2.9-5</version>
</dependency>
ap-loader-all
which contains the native libraries for all platforms for which async-profiler has pre-built libraries and artifacts that only support a single platform like ap-loader-macos
. I recommend using the ap-loader-all
if you don't know what you're doing, the current release is still tiny, with 825KB.AsyncProfilerLoader
class: Wraps async-profiler and jattach, adding a few helper methodsconverter
package: Contains all classes from the async-profiler converter JAR and helps to convert between multiple formatsAsyncProfiler
class: API for async-profiler itself, wrapping the native library.AsyncProfilerLoader
class is just copied from the underlying async-profiler release. ap-loader contains all Java classes from async-profiler, but I omit the helper classes here for brevity.one.profiler
package like the AsyncProfiler class. Probably the most essential method is load
:load
method loads the included async-profiler library for the current platform:AsyncProfiler profiler = AsyncProfilerLoader.load();
IllegalStateException
if the present ap-loader dependencies do not support the platform and an IOException
if loading the library resulted in other problems.AsyncProfiler#getInstance()
method, which can also load an included library. The main difference is that you have to include the native library for all the different platforms, replicating all the work of the ap-loader build system every time you update async-profiler.loadOrNull
method which returns null
instead and also the isSupported
to check whether the current combination of OS and CPU is supported. A typical use case could be:if (AsyncProfilerLoader.isSupported()) {
AsyncProfilerLoader.load().start(...);
} else {
// use JFR or other fall-backs
}
IOException
s, but they should never happen in normal circumstances and are probably by problems that should be investigated, being either an error in ap-loader or in your application.getAsyncProfilerPath method
which throws the same exceptions as the load
method. A similar method exists for jattach (getJattachPath
).profiler.sh
script (will be replaced by asprof
starting with async-profiler 2.10):To run the agent and pass commands to it, the helper scriptprofiler.sh
is provided. A typical workflow would be to launch your Java application, attach the agent and start profiling, exercise your performance scenario, and then stop profiling. The agent's output, including the profiling results, will be displayed in the Java application's standard output.
Async-Profiler documentation
java -jar ap-loader profiler ...
, the API exposes this functionality via ExecutionResult executeProfiler(String... args)
.AsyncProfilerLoader.executeProfiler("-e", "wall", "8983")
// is equivalent to
./profiler.sh -e wall -t -i 5ms -f result.html 8983
executeProfiler
method throws an IllegalStateException
if the current platform is not supported. The returned instance of ExecutionResult
contains the standard and error output:public static class ExecutionResult {
private final String stdout;
private final String stderr;
// getter and constructor
...
}
executeProfiler
throws an IOException
if the profiler execution failed.one.profiler.converter
, but you can also execute the converter by calling ExecutionResult executeProfiler(String... args)
, e.g., the following:AsyncProfilerLoader.executeConverter(
"jfr2flame", "<input.jfr>", "<output.html>")
// is equivalent to
java -cp converter.jar \
jfr2flame <input.jfr> <output.html>
executeConverter
returns the output of the conversion tool on success and throws an IOException
on error, as before.getJattachPath
: ExecutionResult executeJattach(String... args)
and boolean jattach(Path agentPath[, String arguments])
.executeJattach
works similar to executeProfiler
, e.g.:AsyncProfilerLoader.executeJattach(
"<pid>", "load", "instrument", "false", "javaagent.jar=arguments")
// is equivalent to
jattach <pid> load instrument false "javaagent.jar=arguments"
libasyncProfiler.so
is mapped to the extracted async-profiler library for the load command.AsyncProfilerLoader.executeJattach(
PID, "load", "libasyncProfiler.so", true, "start")
executeProfiler
method, which internally uses jattach.VirtualMachine#attach
throws an IOException if you try this without setting -Djdk.attach.allowAttachSelf=true
. The boolean jattach(Path agentPath[, String arguments])
methods simplify this, constructing the command line arguments for you and returning true if jattach succeeded, e.g.:AsyncProfilerLoader.jattach("libjni.so")
libjni.so
agent to the current JVM. The process id of this JVM can be obtained by using the getProcessId
method./**
* extract the native library and return its temporary path
*/
public static synchronized Path getNativeLibPath(
ClassLoader loader) {
if (nativeLibPath == null) {
try {
String filename = System.mapLibraryName(NATIVE_LIB);
InputStream in = loader.getResourceAsStream(filename);
// ...
} catch (IOException e) {
throw new RuntimeException(e);
}
}
return nativeLibPath;
}
extractCustomLibraryFromResources
method:/**
* Extracts a custom native library from the resources and
* returns the alternative source if the file is not
* in the resources.
*
* If the file is extracted, then it is copied to
* a new temporary folder which is deleted upon JVM exit.
*
* This method is mainly seen as a helper method
* to obtain custom native agents for #jattach(Path) and
* #jattach(Path, String). It is included in ap-loader
* to make it easier to write applications that need
* custom native libraries.
*
* This method works on all architectures.
*
* @param classLoader the class loader to load
* the resources from
* @param fileName the name of the file to copy,
* maps the library name if the fileName
* does not start with "lib", e.g. "jni"
* will be treated as "libjni.so" on Linux
* and as "libjni.dylib" on macOS
* @param alternativeSource the optional resource directory
* to use if the resource is not found in
* the resources, this is typically the case
* when running the application from an IDE,
* an example would be "src/main/resources"
* or "target/classes" for maven projects
* @return the path of the library
* @throws IOException if the extraction fails and
* the alternative source is not present
* for the current architecture
*/
public static Path extractCustomLibraryFromResources(
ClassLoader classLoader, String fileName,
Path alternativeSource) throws IOException
// extract the agent first from the resources
Path p = one.profiler.AsyncProfilerLoader.
extractCustomLibraryFromResources(
....getClassLoader(), "library name");
// attach the agent to the current JVM
one.profiler.AsyncProfilerLoader.jattach(p, "optional arguments")
// -> returns true if jattach succeeded
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
User | Count |
---|---|
12 | |
10 | |
9 | |
7 | |
7 | |
7 | |
6 | |
6 | |
5 | |
4 |