Using async-profiler with Cryostat

Red Hat build of Cryostat 4

Red Hat Customer Content Services

Abstract

Red Hat build of Cryostat is a Red Hat offering on OpenShift Container Platform. The Using async-profiler with Cryostat document is for users that want to use the async-profiler utility with Cryostat to enable precise CPU-time profiling of program execution as well as VM and native-memory allocations.

Preface

The Red Hat build of Cryostat is a container-native implementation of JDK Flight Recorder (JFR) that you can use to securely monitor the Java Virtual Machine (JVM) performance in workloads that run on an OpenShift Container Platform cluster. You can use Cryostat to start, stop, retrieve, archive, import, and export JFR data for JVMs inside your containerized applications by using a web console or an HTTP API.

Depending on your use case, you can store and analyze your recordings directly on your Red Hat OpenShift cluster by using the built-in tools that Cryostat provides or you can export recordings to an external monitoring application to perform a more in-depth analysis of your recorded data.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Async-profiler integration

From Cryostat 4.2 onward, Cryostat supports integration with the Content from github.com is not included.async-profiler utility as a beta-level feature. The async-profiler is an open-source, low-overhead sampling profiler for JDKs that are based on the Content from www.oracle.com is not included.Java HotSpot Performance Engine.

Because it can capture stack traces without waiting for JVM safepoints, the async-profiler helps to provide accurate performance analysis by identifying issues such as central processing unit (CPU) bottlenecks, memory leaks, and lock contention between multiple processes.

By using the async-profiler with Cryostat, you can enable precise CPU-time profiling of program execution as well as virtual machine (VM) and native memory allocations. The async-profiler supports a series of predefined event types that you can use as the basis for setting up a customized profiling session for a specific target JVM and timeframe. Only one profiling session may exist for a specific target at any given time.

The Cryostat web console provides an async-profiler view where you can create and delete customized profiling sessions, as required. You can also download profiling session files for offline analysis.

Note

Cryostat support for async-profiler integration is a beta-level feature only.

Chapter 2. Enabling a target JVM to support async-profiler integration

The async-profiler utility is not supplied as part of a Cryostat or Cryostat Operator deployment. Cryostat does not implement any method for supplying the async-profiler‘s Java archive (.jar) and shared object (.so) files to your target application. If you want to use the async-profiler with Cryostat, you maintain responsibility for obtaining the async-profiler.jar and async-profiler.so files and ensuring that your application image contains these files. In addition, you must ensure that you are using async-profiler 4.3 or later.

Note

Cryostat support for async-profiler integration is only available for target JVMs that are using the Cryostat agent for connection to Cryostat. This feature is not available for target JVMs that are using a JMX connection.

Prerequisites

Procedure

  • Attach the async-profiler.jar file to the JVM at startup by using the -javaagent JVM flag.

    For example: 

    java -javaagent:build/jar/async-profiler.jar -Djava.library.path=build/lib myapp.java

    When you run the preceding command, it also allows Cryostat to connect remotely to the async-profiler’s MXBean.

    Note

    As shown in the preceding example, the async-profiler requires that you use a static -javaagent JVM flag to attach its JAR file to the JVM. However, async-profiler integration is supported regardless of whether you want the Cryostat agent to use a static or dynamic approach for attaching to the JVM. For more information about the different ways the Cryostat agent can attach to the JVM, see This content is not included.Static or dynamic attachment to the JVM.

Chapter 3. Enabling beta-level graphical features in the Cryostat web console

Only production-level graphical features appear by default in the Cryostat web console. Any experimental beta-level graphical features are hidden from view by default.

Because async-profiler integration is a beta-level feature only, its associated view is not automatically available for selection from the Cryostat web console navigation menu. If you want to create async-profiler profiling sessions in the Cryostat web console, you must first enable the web console to show beta-level graphical features.

Procedure

  1. Open the Cryostat web console.
  2. In the upper-right area of the console, click the Settings icon. The Settings panel then opens.
  3. From the left-hand navigation pane, select Advanced.

  4. From the Feature level drop-down list, select Beta.

    Figure 3.1. Enabling the web console to show beta-level features

    Enabling the web console to show beta-level features

    The async-profiler option then automatically appears under the Flight Recording > Capture view in the Cryostat web console navigation menu.

Chapter 4. Creating an async-profiler profiling session

You can use the Flight Recorder > Capture > async-profiler view of the Cryostat web console to create customized profiling sessions for a selected target JVM and specified duration. Only one profiling session may exist for a specific target at any given time. You can set up a profiling session by selecting from a predefined series of event types that you want to use as the basis for the profiling activity.

Prerequisites

Procedure

  1. From the Cryostat web console navigation menu, select Flight Recorder > Capture > async-profiler.
  2. From the Target drop-down list, select the target JVM for which you want to create a profiling session.

  3. Depending on the target JVM that you select, consider the following information:

    • If the selected target is not configured to load the Cryostat agent, the async-profiler panel displays a message to this effect.

      Figure 4.1. Example panel when target JVM is not configured to load the Cryostat agent

      *Example panel when target JVM is not configured to load the Cryostat agent

    • If the selected target is configured to load the Cryostat agent but not currently enabled to support async-profiler integration, the async-profiler panel displays a message to this effect.

      Figure 4.2. Example panel when async-profiler integration is not enabled for selected target

      *Example panel when async-profiler integration is not enabled for selected target

      For more information, see Enabling a target JVM to support async-profiler integration.

    • If the selected target is enabled to support async-profiler integration but no profiling sessions currently exist, the async-profiler panel displays a message to this effect.

      Figure 4.3. Example panel when no profiling sessions exist for selected target

      *Example panel when no profiling sessions exist for selected target

  4. To create a profiling session:

    1. In the async-profiler panel, click Create. This opens an async-profiler > Create panel.

      Figure 4.4. Creating an async-profiler profiling session

      *Creating an async-profiler profiling session

    2. From the Available options list, select the checkbox next to each event type that you want to include in this profiling session. Then click the > button to move the selected event types to the Chosen options list. If you click the >> button, it moves all available options to the Chosen options list automatically.

      If you subsequently want to deselect an event type, select the checkbox next to this item in the Chosen options list, and then click the < button to move it back to the Available options list. If you click the << button, it moves all chosen options back to the Available options list automatically.

    3. In the Duration field, enter a numeric value that corresponds to the length of time for which this profiling session is to remain active. You can specify this value in units of seconds, minutes, or hours by selecting the appropriate option from the drop-down list. The profiling session automatically stops after the specified duration has elapsed.

    4. Click Create.

      Note

      Because some async-profiler event types are mutually exclusive, Cryostat performs a validation check at this point to ensure that you have selected a valid combination of event types.

      If you have not selected a valid combination of event types, Cryostat instructs you to modify your list of chosen options before it can create the profiling session.

      If you have selected a valid combination of event types, Cryostat creates the profiling session, and it is added to the table in the async-profiler panel. The Create button on the async-profiler panel is automatically disabled while the current profiling session remains active.

Chapter 5. Downloading a profiling session

You can use the async-profiler panel in the Cryostat web console to download profiling session files for offline analysis.

Prerequisites

Procedure

  1. In the async-profiler panel, click the overflow icon next to the profiling session you want to download.

    Figure 5.1. Downloading a profiling session file

    Downloading a profiling session file
  2. From the overflow menu, select Download. The profiling session file is then downloaded to your local system in JFR file format for further analysis.

Chapter 6. Deleting a profiling session

You can use the async-profiler panel in the Cryostat web console to delete profiling session files.

Note

Similar to active flight recordings, the data for async-profiler profiling sessions remains resident in your target application’s JVM memory. Cryostat does not currently support the ability to copy profiling session files to Cryostat storage.

Procedure

  1. In the async-profiler panel, select the checkbox next to the profiling session you want to delete.
  2. Click Delete.

Revised on 2026-05-26 17:49:22 UTC

Legal Notice

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.