Frequently asked questions about the Azure Command Launcher for Java (public preview)

Provides answers to common questions about the Azure Command Launcher for Java.

How is this tool different from the java command?

The java command runs the HotSpot JVM (Java Virtual Machine) with default settings unless explicitly configured by the user. jaz is a component of the Azure Command Launcher for Java that launches java with battle-tested, cloud-optimized JVM tuning defaults, designed to improve performance and cost-efficiency on Azure VMs and containers.

Key benefit: developers don't need to manually tune the JVM. jaz does it for them.

What happens if I already set some JVM options in my environment?

If your workload includes JVM tuning flags, the jaz command doesn't apply its own tuning defaults. jaz launches java with the flags you chose.

We recommend removing your workload's tuning flags and letting the Azure Command Launcher for Java apply its own.

You can also configure jaz to ignore your tuning flags and use its tuning defaults. Consider using this configuration to validate jaz with minimal change to your workload configuration. To do so, set the following environment variable:

export JAZ_IGNORE_USER_TUNING=1

The ignore user tuning setting applies to command line arguments, environment variables read by java, and @-files.

You can also configure jaz to skip all of its tuning defaults by setting the following environment variable:

export JAZ_BYPASS=1

The bypass option allows you to onboard to the Azure Command Launcher for Java without affecting your current tuning, even if your workload uses the default behavior of the java command. This behavior may be useful to validate the tool's behavior before cleaning up JVM tuning flags.

It may also be useful to bypass tuning when troubleshooting an issue that appears to be related to JVM tuning.

What JVM options are considered tuning flags?

The jaz command considers most flags that start with -X or -XX to be a tuning flag, such as -Xmx<size>. A notable example of a flag that starts with -X but isn't a tuning flag is -Xlog:<opts>.

More precisely, each JVM option is evaluated using the logic in the following list. This list describes the logic in the most recent version of the Azure Command Launcher for Java.

  1. If the option starts with any text other than -X, it's not a tuning flag.
  2. If the option matches any of these regular expressions, it's not a tuning flag:
    • ^-Xlog.+$
    • ^-XX:ErrorFile=.*$
    • ^-XX:[+-]?HeapDump.*$
    • ^-XX:[+-].*OnOutOfMemoryError$
  3. Otherwise, the option is a tuning flag.

When jaz looks for tuning flags, it examines the arguments passed to it and the environment variables that java reads automatically. The environment variables are:

  • Java 8: JAVA_TOOL_OPTIONS, _JAVA_OPTIONS
  • Java 9 and later: JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, _JAVA_OPTIONS

jaz also handles @-files, also known as command line argument files.

Can I pass java agent flags when using the tool?

Yes. You can still pass -javaagent and other flags that aren't tuning flags, and jaz honors them. You can keep useful diagnostic flags such as:

  • -Xlog for logging
  • -javaagent for Application Insights or other Application Performance Monitoring (APM) instrumentation agents

Is the tool compatible with non-Azure environments?

jaz is designed and tested primarily for Azure Containers and Virtual Machines, but it can technically run elsewhere. However, some advanced optimizations and future features might be Azure-specific.

Is the tool available for Windows Server?

jaz is currently available for Linux on x64 and arm64 environments. If you have an immediate need for Windows Server, please contact us at openjdk-support@microsoft.com.

The Azure Command Launcher for Java has been tested and certified only with full JDK installations. It may not work correctly with:

  • JRE (Java Runtime Environment) installations
  • Custom jlink runtimes

Full JDK installations include all the tools and libraries that jaz requires to work properly. JRE and jlink custom runtimes may lack some of these components, which can prevent jaz from functioning as expected.

Why does my cgroup mount point matter?

The Azure Command Launcher for Java reads cgroup v1 and v2 information from /sys/fs/cgroup to determine the available resources, such as memory limits and CPU constraints, and tune the JVM accordingly. If the cgroup filesystem isn't mounted at the standard /sys/fs/cgroup location, jaz might not detect containerization limits correctly. This can lead to poor performance or even out-of-memory errors because jaz might tune the JVM based on the host's resources rather than the container's actual limits.

We haven't identified a real-world scenario where the cgroup mount point is something other than /sys/fs/cgroup. However, it's possible to simulate this scenario in a container by unmounting the cgroup filesystem from /sys/fs/cgroup and mounting it at a different location. Then, jaz won't be able to read the cgroup information and won't apply container-aware tuning.

To avoid issues, don't change your cgroup mount point from the standard /sys/fs/cgroup location.

While cgroup mount points are most relevant in containerized environments, they can also be relevant in virtual machines and other Linux environments that use cgroups for resource management.

Does the tool work with nested cgroup configurations?

Nested cgroup configurations can affect how the Azure Command Launcher for Java reads resource limits. jaz hasn't been tested with nested cgroup hierarchies, so it might not detect resource constraints correctly in these environments.

If you're using nested cgroups and experience unexpected behavior, please contact us at openjdk-support@microsoft.com.