Package one.profiler

Class AsyncProfilerLoader

java.lang.Object

one.profiler.AsyncProfilerLoader

public final class AsyncProfilerLoader
extends Object

Allows to work with the async-profiler libraries and tools stored in the resources folder.

Upon extraction the libraries and tools are stored in an application, version and user specific application folder. The resulting files are therefore cached between executions of the JVM. This folder can be manually specified by either setting the property ap_loader_extraction_dir or by using the setExtractionDirectory(Path)} method.

Running this class as an agent main class, makes it an agent that behaves the same as the libasyncProfiler.so agent. Running the main method exposed the profiler.sh, jattach and converter features.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AsyncProfilerLoader.ExecutionResult	Output and error output of a successful process execution.

Constructor Summary

Constructors

Constructor	Description
AsyncProfilerLoader()

Method Summary

Modifier and Type	Method	Description
static void	agentmain(String agentArgs, Instrumentation instrumentation)
static void	attach(String arguments)	Attach the extracted async-profiler agent to the current JVM.
static void	deleteExtractionDirectory()	Deletes the directory used for extraction
static AsyncProfilerLoader.ExecutionResult	executeConverter(String... args)	See converter for more information.
static AsyncProfilerLoader.ExecutionResult	executeJattach(String... args)	See jattach for more information.
static AsyncProfilerLoader.ExecutionResult	executeProfiler(String... args)	See profiler.sh for more information.
static Path	extractCustomLibraryFromResources(ClassLoader classLoader, String fileName)	Extracts a custom agent from the resources
static Path	extractCustomLibraryFromResources(ClassLoader classLoader, String fileName, Path alternativeSource)	Extracts a custom native library from the resources and returns the alternative source if the file is not in the resources.
static Path	getAsyncProfilerPath()	Extracts the async-profiler and returns the path to the extracted file.
static List<String>	getAvailableVersions()	Get available versions of the library
static Path	getExtractionDirectory()	Returns the directory used for storing the extracted libraries, binaries and JARs
static Path	getJattachPath()	Extracts the jattach tool
static int	getProcessId()	Returns the id of the current process
static String	getVersion()	Returns the version of the included async-profiler library (or the version set by setVersion(String)
static boolean	isSupported()	Checks if an async-profiler library for the current OS, architecture and glibc is available in this JAR.
static boolean	jattach(Path agentPath)	See jattach for more information.
static boolean	jattach(Path agentPath, String arguments)	See jattach for more information.
static AsyncProfiler	load()	Loads the included async-profiler for the current OS, architecture and glibc
static AsyncProfiler	loadOrNull()	Loads the included async-profiler for the current OS, architecture and glibc.
static void	main(String[] args)
static void	premain(String agentArgs, Instrumentation instrumentation)
static void	setExtractionDirectory(Path extractionDir)	Returns directory used for storing the extracted libraries, binaries and JARs
static void	setVersion(String version)	Set the used version of async-profiler.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

AsyncProfilerLoader

public AsyncProfilerLoader()

Method Details

setExtractionDirectory

public static void setExtractionDirectory(Path extractionDir)

Returns directory used for storing the extracted libraries, binaries and JARs

setVersion

public static void setVersion(String version)
                       throws IOException

Set the used version of async-profiler. This is required if there are multiple versions of this library in the dependencies.

Parameters:

version - set version of async-profiler to use

Throws:

IOException

deleteExtractionDirectory

public static void deleteExtractionDirectory()
                                      throws IOException

Deletes the directory used for extraction

Throws:

IOException

getExtractionDirectory

public static Path getExtractionDirectory()
                                   throws IOException

Returns the directory used for storing the extracted libraries, binaries and JARs

Throws:

IOException

getAvailableVersions

public static List<String> getAvailableVersions()

Get available versions of the library

getVersion

public static String getVersion()

Returns the version of the included async-profiler library (or the version set by setVersion(String)

Throws:

IllegalStateException - if the version could not be determined

isSupported

public static boolean isSupported()

Checks if an async-profiler library for the current OS, architecture and glibc is available in this JAR.

Returns:

true if a library is available, false otherwise

extractCustomLibraryFromResources

public static Path extractCustomLibraryFromResources(ClassLoader classLoader,
 String fileName)
                                              throws IOException

Extracts a custom agent from the resources

Parameters:

classLoader - the class loader to load the resources from

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

Returns:

the path of the library

Throws:

IOException - if the extraction fails

extractCustomLibraryFromResources

public static Path extractCustomLibraryFromResources(ClassLoader classLoader,
 String fileName,
 Path alternativeSource)
                                              throws IOException

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.

Parameters:

classLoader - the class loader to load the resources from

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

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

Returns:

the path of the library

Throws:

IOException - if the extraction fails and the alternative source is not present for the current architecture

getJattachPath

public static Path getJattachPath()
                           throws IOException

Extracts the jattach tool

Returns:

path to the extracted jattach tool

Throws:

IllegalStateException - if OS or arch are not supported

IOException - if the extraction fails

getAsyncProfilerPath

public static Path getAsyncProfilerPath()
                                 throws IOException

Extracts the async-profiler and returns the path to the extracted file.

Returns:

the path to the extracted library

Throws:

IOException - if the library could not be loaded

IllegalStateException - if OS or Arch are not supported

executeJattach

public static AsyncProfilerLoader.ExecutionResult executeJattach(String... args)
                                                          throws IOException

See jattach for more information.

It runs the same as jattach with the only exception that every string that ends with "libasyncProfiler.so" and "libasyncProfiler.dylib" are mapped to the extracted async-profiler library for the load command. One can therefore start/stop the async-profiler via executeJattach(PID, "load", "libasyncProfiler.so", true, "start"/"stop").

Use the jattach(Path) or jattach(Path, String) to load agents via jattach directly, without the need to construct the command line arguments yourself.

Throws:

IOException - if something went wrong (e.g. the jattach binary is not found or the execution fails)

IllegalStateException - if OS or Arch are not supported

jattach

public static boolean jattach(Path agentPath)

See jattach for more information.

It loads the passed agent via jattach to the current JVM, mapping "libasyncProfiler.so" and "libasyncProfiler.dylib" to the extracted async-profiler library for the load command.

Returns:

true if the agent was successfully attached, false otherwise

Throws:

IllegalStateException - if OS or Arch are not supported

jattach

public static boolean jattach(Path agentPath,
 String arguments)

See jattach for more information.

It loads the passed agent via jattach to the current JVM, mapping "libasyncProfiler.so" and "libasyncProfiler.dylib" to the extracted async-profiler library for the load command.

Returns:

true if the agent was successfully attached, false otherwise

Throws:

IllegalStateException - if OS or Arch are not supported

executeConverter

public static AsyncProfilerLoader.ExecutionResult executeConverter(String... args)
                                                            throws IOException

See converter for more information.

Just pass it the arguments that you would normally pass to the JVM after java -cp converter.jar

Throws:

IOException - if something went wrong (e.g. the execution fails)

IllegalStateException - if OS or Arch are not supported

executeProfiler

public static AsyncProfilerLoader.ExecutionResult executeProfiler(String... args)
                                                           throws IOException

See profiler.sh for more information.

Throws:

IOException - if something went wrong (e.g. the execution fails)

IllegalStateException - if OS or Arch are not supported

loadOrNull

public static AsyncProfiler loadOrNull()

Loads the included async-profiler for the current OS, architecture and glibc.

Returns:

the loaded async-profiler or null if anything went wrong (e.g. unsupported OS)

load

public static AsyncProfiler load()
                          throws IOException

Loads the included async-profiler for the current OS, architecture and glibc

Returns:

the loaded async-profiler

Throws:

IOException - if the library could not be loaded

IllegalStateException - if OS or arch are not supported

premain

public static void premain(String agentArgs,
 Instrumentation instrumentation)

getProcessId

public static int getProcessId()

Returns the id of the current process

Throws:

IllegalStateException - if the id can not be obtained, this should never happen

attach

public static void attach(String arguments)

Attach the extracted async-profiler agent to the current JVM.

Parameters:

arguments - arguments string passed to the agent, might be null

Throws:

IllegalStateException - if the agent could not be attached

agentmain

public static void agentmain(String agentArgs,
 Instrumentation instrumentation)

main

public static void main(String[] args)
                 throws IOException

Throws:

IOException