Visit Azul.com Support

Using ReadyNow Orchestrator

Using ReadyNow involves two distinct phases:

  • Recording a good profile log that accurately captures the usage pattern you want to warm up. Recordings can be refined automatically through repetitive training cycles.

  • Using the profile log as the input to newly started VMs.

Using the Optimizer Hub ReadyNow Orchestrator to record and serve profile logs, greatly simplifies the operational use of ReadyNow.

  • There is no need to configure any local storage for writing the profile log.

  • ReadyNow Orchestrator handles recording multiple profile candidates from multiple JVMs and promoting the best recorded profile log. You no longer need to manually prepare a profile and then distribute it before rolling out new versions of your code. Instead, you can generate the profile automatically in production as part of your fleet restart.

  • ReadyNow Orchestrator monitors the optimization profiles of an entire fleet of JVMs rather than just one JVM, intelligently picking the best one.

Creating and Writing To a New Profile Name

You use ReadyNow Orchestrator by creating a connection to the Optimizer Hub and specifying the criteria for reading and writing profile logs. All of the necessary options can be specified as command-line arguments to the Java process at the time of deployment.

The basic lifecycle of using ReadyNow profile logs is as follows:

  • The JVM streams profile log output to ReadyNow Orchestrator, giving the output a unique profile name.

  • Based on basic criteria specified in the command-line arguments, the JVM nominates the output profile log as a candidate for sharing with other JVMs.

  • ReadyNow Orchestrator deals with candidate profile logs arriving from various JVMs that use the same profile name.

  • Whenever the service receives a request for a profile log with a given profile name, it examines the candidates it has collected and serves up the best one. This can change over time as ReadyNow Orchestrator receives new and more complete profile log candidates.

  • JVMs can request multiple generations of a profile log. Rather than starting with no input profile log and recording its output log based on the regular JIT profiling process, the JVM can take a profile log as the input and further refine the profiling information, recording its experience as a new generation of that profile log. If you need to minimize the chances of having any deoptimizations through the life of your Java program, it is sometimes beneficial to record several generations. ReadyNow Orchestrator always serves the newest generation for a profile name to JVMs. JVMs can cap the number of generations that they write out to avoid developing the profile forever.

ReadyNow Orchestrator JVM Options

The following options are available in Azul Prime when using ReadyNow Orchestrator with Optimizer Hub:

Command Line Option Description Default

-XX:OptHubHost={host:port}

Address where Optimizer Hub is listening. The default is localhost:50051. See Connecting a JVM to Optimizer Hub for how instructions on determining the correct host and port.

null

-XX:ProfileLogName={profilePath}

Name of the profile that the JVM both reads from and writes to. Use of this flag is equivalent to using -XX:ProfileLogIn={profilePath} -XX:ProfileLogOut={profilePath}, and is the preferred way to specify profile names when different input and output names are not needed. If prefixed with opthub://, {profilePath} is used as the profile name in ReadyNow Orchestrator. If not prefixed with opthub://, {profilePath} is interpreted as a file path on the JVM.

null

-XX:ProfileLogOut={profilePath}

The ProfileLogOut enables Azul Zulu Prime JVM to record compilations from the current run. {profilePath} is the name of the profile that the JVM reads as input to ReadyNow. If prefixed with opthub://, {profilePath} is used as the profile name in ReadyNow Orchestrator. If not prefixed with opthub://, {profilePath} is interpreted as a file path on the JVM.

null

-XX:ProfileLogIn={profilePath}

The ProfileLogIn allows Azul Zulu Prime JVM to base its decisions on the information from a previous run. The current ProfileLogIn file information will be read in its entirety - before Azul Zulu Prime JVM starts to create a new ProfileLogOut log. {profilePath} is the name of the profile that the JVM reads as input to ReadyNow. If prefixed with opthub://, {profilePath} is used as the profile name in ReadyNow Orchestrator. If not prefixed with opthub://, {profilePath} is interpreted as a file path on the JVM.

null

-XX:ProfileLogOutNominationMinSize

Indicate to server that the produced profile is eligible for promotion after specified amount of bytes recorded.

0 = any size eligible

-1 = will never be promoted

1M

-XX:ProfileLogOutNominationMinSizePerGeneration

Define minimum acceptable amount of bytes per generation which the profile size should reach to become eligible for promotion.

null

-XX:ProfileLogOutNominationMinTimeSec

When used with ReadyNow Orchestrator, the minimum time, in seconds, a profile must record before ReadyNow Orchestrator will nominate it as a candidate.

0 = any duration eligible

-1 = will never be promoted

120

-XX:ProfileLogOutNominationMinTimeSecPerGeneration

When used with ReadyNow Orchestrator, the minimum time, in seconds, per generation during which the profile should be recorded in order to become eligible for promotion.

null

-XX:ProfileLogOutMaxNominatedGenerationCount

When used with ReadyNow Orchestrator, specifies the maximum generation of a profile that a VM will nominate. This JVM command line parameter overrides the serverside default to configure ReadyNow Orchestrator.

0 = unlimited

0

-XX:ProfileLogMaxSize={value in bytes}

Specifies the maximum size that a ReadyNow profile log is allowed to reach. Profiles will be truncated at this size, regardless of whether the application has actually been completely warmed up.

This JVM command line parameter overrides the serverside default to configure ReadyNow Orchestrator.

It is recommended to either not set this size explicitly, or set it generously if required, for example:

-XX:ProfileLogMaxSize=1G

0 = unlimited

0

-XX:ProfileLogTimeLimitSeconds={value in seconds}

Instructs ReadyNow to stop adding to the profile log after a period of N seconds regardless of where the application has been completely warmed up. It is recommended to either not set this size explicitly, or set it generously if required.

0 = unlimited

0

-XX:ProfileLogDumpInputToFile={name}

Dumps input profile to the specified path. For debugging purposes only.

null

-XX:ProfileLogDumpOutputToFile={name}

Dumps output profile to the specified path. For debugging purposes only.

null

-XX:RNOConnectionTimeoutMillis

Timeout on establishing remote connection and timeout on interval between downloading two chunks. Specified in milliseconds.

5000

-XX:RNOProfileFallbackInput

Experimental feature. Local filesystem path which gets used in case no profile data is downloaded. E.g., in case of a missing connection or the requested profile name doesn’t exist on the server.

null

-XX:ProfileLogOutVerbose

Enables logging of verbose, optional tracing information in -XX:ProfileLogOut

true

Substitution Macros

The profile name is the central organizing attribute that ReadyNow Orchestrator uses to group together profile logs. ReadyNow Orchestrator regards all candidates it receives that contain the same profile name as being for the same application, with no further knowledge of what code was actually runs. This poses the danger of accidentally using the same profile name for two different applications. For example, if a user copies and pastes the command-line arguments, including the profile name, from a production application and uses it to run HelloWorld, the HelloWorld profile could, in some cases, replace your valid production application profile.

To avoid this danger, you can use substitution macros in your profile name to limit the likelihood of profile name clashes between different applications. Each macro unfolds to a 4-byte hash string taken from a particular plain-text string corresponding to a property:

Macro Description

%classpathhash

Hashed user-defined Java class path string

%vmargshash

Hashed JVM arguments string

%vmflagshash

Hashed JVM flags string

%cmdlinehash

Hashed string containing all plain-text values from above macros. Input values are concatenated to one string: Java class path string + JVM arguments string + JVM flags string. Afterwards, 4-bytes hash is applied to concatenated result.

%jdkver

Hashed JDK version number converted to string

%jvmver

Hashed JVM version number converted to string

%prop={PROPERTY}%

Substition macro defining the profile log name. This gets replaced with the value of the corresponding Java system property. Provide these properties to the JVM on startup with -Dprop=value.

For example:

 
-Dmyprofilename=test-profileout \ -XX:ProfileLogOut=opthub://%prop=myprofilename%

Basic Profile Recording with Defaults

In its most basic form, you just let the defaults do all the work. By default, ReadyNow Orchestrator will nominate profile logs after three full generations and does not place a limit on log size. Suppose you want to record a new profile while deploying code to a fleet running in production. Run with the following options:

 
java -XX:OptHubHost=TestEnvOptHubHost \ -XX:ProfileLogName=opthub://MyApp-v3 \ -jar myapp.jar

In this case, all JVMs nominate their logs based on the defaults (e.g. 2 minutes for the first generation, 15 minutes for the second generation, etc.) and keep recording until the JVM shuts down. For best results, do a test run in a canary instance for at least two minutes and if possible a full ten minutes. This creates generation 1 of your profile. Then restart your fleet as normal. As JVMs start up, they receive a profile from ReadyNow Orchestrator and check the generation number. If that number is less than the server-side default maximum of 3, the JVM writes out the next generation of the profile. Once there is a valid generation 3 of the profile on ReadyNow Orchestrator, none of the JVMs write any more output.

Capping Profile Log Recording and Maximum Generations

We can make our example above more complex:

  • After 10 minutes you want to stop recording.

  • You want to record two generations of the profile.

Start your JVM with the following parameters:

 
java -XX:OptHubHost=TestEnvOptHubHost \ -XX:ProfileLogName=opthub://MyApp-v3 \ -XX:ProfileLogTimeLimitSeconds=600 \ -XX:ProfileLogOutMaxNominatedGenerationCount=2 \ -jar myapp.jar

Using a Previous Profile as the Basis of a New Profile Recording

When you’re deploying version 3 of MyApp, you often have a valid profile for version 2. In most cases, you change a small portion of your code between versions and most of the previous profile is still valid for your new version. When you feed in the previous version of the profile as input to recording the new version of the profile, you can in most cases eliminate the need to do multiple training iterations.

Using our above example, perform one run of the full ten minutes in a canary with the following settings:

 
java -XX:OptHubHost=TestEnvOptHubHost \ -XX:ProfileLogIn=opthub://MyApp-v2 \ -XX:ProfileLogOut=opthub://MyApp-v3 \ -XX:ProfileLogTimeLimitSeconds=600 \ -XX:ProfileLogOutMaxNominatedGenerationCount=1 \ -jar myapp.jar

To restart the rest of your fleet with the following settings:

 
java -XX:OptHubHost=TestEnvOptHubHost \ -XX:ProfileLogName=opthub://MyApp-v3 \ -XX:ProfileLogTimeLimitSeconds=600 \ -XX:ProfileLogOutMaxNominatedGenerationCount=1 \ -jar myapp.jar