Visit Azul.com Support

CRS Configuration Options

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

The Connected Runtime Service (CRS) is the component inside the JVM that runs your applications or in the Intelligence Cloud Agent that runs next to your applications. CRS collects the dependency information of your application, and sends it via the Forwarder to Azul Intelligence Cloud. On this page, you find all the configuration options for normal usage. Next to these options, there are also Diagnostics Configuration Options.

Configuration Options

CRS Mode

Note
 This configuration option is only applicable when you use an Azul JDK or JRE. It’s not available for the Azul Intelligence Cloud Agent.

The CRS Mode can be configured with the -XX:AzCRSMode startup argument and has the following options:

  • auto: This is the default value. CRS decides whether it needs to start in the main method, and excludes tools like javap, javac having a specific main method in com.sun.tools.

  • on: Forces CRS to start, if all required configurations are available (e.g. endpoint), even for tools like javap, javac.

  • off: Forces CRS to be disabled.

Usage Example

 
java -XX:AzCRSMode=on -jar MyApp.jar

CRS Runtime Instance Tags

Note
 This configuration option is available for both the Azul Intelligence Cloud Agent and when using an Azul JDK or JRE.

A runtime tag is a user-defined key-value pair associated with an instance. Tags are used to search, categorize, and organize instances logically in the Azul Intelligence Cloud Web UI. Unlike instance IDs, tags are not unique. You can add the same tag to multiple instances as well as add multiple tags to one instance.

Applying Tags

Tag keys must begin with a letter. Both key and value may contain lower and upper case letters, and numbers. These additional characters are also allowed:

 
ALLOWED_KEY_EXTRA_CHARS = "-_."
ALLOWED_VALUE_EXTRA_CHARS = "-_. :/@" <-- Includes space

Tags can be provided both as environment variable and in command line options. When using both, the results are combined. It’s recommended to use environment variables as it allows AZ_CRS_ARGUMENTS to be mostly the same for each JVM.

Special Tags

This tag is handled in a specific way with the system:

Tag Description Example

AppEnv

To use the "Code Inventory Summarization" feature, you need to configure an AppEnv value on the machine where you run the JVM. The value is, for example, the application name. This information is sent through the Forwarder to the Azul Intelligence Cloud system, together with information about the components, classes, and methods that are used.

AppEnv also scopes Forwarder 2.0.0 deduplication. The Forwarder deduplicates class and method events within the same AppEnv group. Use a consistent AppEnv value for JVMs that belong to the same application environment.

Note
 When you don’t specify AppEnv, in combination with Agent 1.2+ and Forwarder 2+, the JVM is ignored and no data is sent to Intelligence Cloud, as deduplication cannot be applied.

AppEnv=test

How to Use Tags

Tags can be specified with a command line argument or environment variable:

 
# With command line option
-Dcom.azul.crs.instance.tags="system-prop.tag_1=system prop/value@1; system_prop_tag.2=system prop:value/2"

# With environment variable
export CRS_TAGS="env.tag-1=value:1; env_Tag_2=value 2"

For example, using the command line option:

 
java -XX:AzCRSMode=on \
    -XX:AzCRSArguments=api.url=https://<FORWARDER_IP:PORT> \
    -Dcom.azul.crs.instance.tags="AppEnv=MyApplicationTag" \
    -jar MyApp.jar

It is important that you properly tag your instances. As a general rule, tagging should reflect the way you categorize your Java applications. For example, you can use "west-coast", "east-coast", and so on to distinguish between different availability zones/locations.

When you use Forwarder 2.0.0, review your AppEnv tagging strategy before enabling production traffic. If unrelated applications share the same AppEnv, deduplication groups their events together and report accuracy can degrade.

Automated Tags

Some instance properties are detected automatically. For example, you don’t have to tag the Java version, because it’s detected by CRS.

CRS Arguments

Note
 This configuration option is available for both the Azul Intelligence Cloud Agent and when using an Azul JDK or JRE.

CRS can be controlled with the following arguments. They need to be specified in a comma-separated value format. Each expression is either <propertyName>=<value>, or just <propertyName> for Boolean properties.

These are the available properties:

Argument Default Description

props=<path>

Location of a properties file to configure CRS.

~/.az_crs/config.properties

api.url=<url>

This is the base URL of your Forwarder instance and must be specified. If no Forwarder is specified, CRS is effectively disabled.

The Forwarder endpoint must be in URL format https://<FORWARDER_IP:PORT>;. https is required, unless you set noSsl=true. The port is optional and must be specified if different then 443.

null

noSsl=<true/false>

Allows an http:// address in api.url, so the Agent connects to the Forwarder over plain HTTP. Without this option, the Agent refuses an http:// address and reports why. This option is available in the Azul Intelligence Cloud Agent since version 1.3.0.

This is intended mainly for Azul Intelligence On-Premises installations, where no Azul-issued certificate is available, and for environments where TLS is terminated by another layer, such as a proxy or load balancer in front of the Forwarder. With Azul Intelligence Cloud, Azul manages the certificates, and you don’t need this option. The Forwarder must allow plain HTTP too, see Forwarder setup for Azul Intelligence On-Premises.

Warning
 With plain HTTP, the authentication token of the Agent and all observations travel unencrypted. Use it only on networks you trust. For production, use HTTPS with a certificate from your own certificate authority.

false

enable=<true/false>

Use this argument when you can’t adjust the command line, to enable or disable the CRS agent. Enabling the CRS agent with enable=true has the same effect as -XX:AzCRSMode=auto.

Note
 When you specify the -XX:AzCRSMode runtime flag, this enable environment variable flag, gets ignored.

true

delayTermination=<value>

Number of milliseconds to hold a JVM alive at its end, providing time to send the collected data to the Forwarder. Raise the value to provide time to short-lived microservices. The provided value is used as a maximum, if CRS takes less time (down to 0), the delay doesn’t use the fully defined duration.

0

delayInitiation=<value>

Number of milliseconds to delay the CRS start. The default enables integration with major Java frameworks. Lower to 0 for short-lived microservices.

2000

stackRecordId=<value>

Suffix of the DNS record to query for an endpoint.

null

sendPOMData=<true/false>

Flag to define if the content of pom.properties files must be sent to Intelligence Cloud.

true

keystore=<value>

If set, this keystore is used to authenticate the JVM with the Forwarder. Set this to a Java keystore file when using self-signed certificates.

If not specified, CRS will use the certificates from the JVM.

null

keystorepassword=<value>

The password for the custom keystore. If it is not provided, the default password is used.

crscrs

notifyJarLoad=<true/false>

Send JAR and component information.

true

notifyClassLoad=<true/false>

Send class level information.

true

notifyFirstCall=<true/false> [1]This option is available in the Azul Intelligence Cloud Agent since version 1.1.22 of January 2025

Enables the Code Inventory functionality at the method level. When set to true, it sends events of the first method execution to your Intelligence Cloud instance through the Forwarder connection.

false

sendClassMethods=<true/false>

Enables the Code Inventory functionality for the "Unused Methods" report. This also requires notifyFirstCall=true.

false

sendCRSLogs=<true/false>

Flag to define if the logs, generated by the agent, must be forwarded to Azul Intelligence Cloud.

true

compressArtifacts=<true/false>

Compresses large reports before they are uploaded. When the Agent reports a JAR with full details (all entries and methods), the report can get large, and reports over 512 KB are uploaded as separate artifacts. With true, the Agent compresses these reports with gzip before the upload, which reduced the upload size by about two thirds in tests (for example, 660 KB to 220 KB). The compression runs in the background upload thread of the Agent, not in the threads of your application. With false, the reports are uploaded uncompressed. This option is available in the Azul Intelligence Cloud Agent since version 1.3.0.

Like the other on/off arguments, this option accepts true/false, yes/no, and on/off.

true

protectAppResources=<true/false>

Flag to define if edge cases of running agents in highly constrained memory environments should be detected, as this may lead to OOM errors. When the agent recognizes that it competes for memory with the application, it will proactively free the memory used by it and terminate itself.

In Azul Intelligence Cloud Agent 2.0.0 and later, use protectAppResources. The legacy memorySafeguards option is deprecated.

Some applications, for example, caches, use the same approach. In such cases, the JVM will also clear its data and the agent can continue without problems. You should not use the protection for this kind of applications.

Side effects to take into account:

  • In some cases, this protection may trigger the termination of the agent when it is not really necessary or too early.

  • The termination triggered by the protection is immediate, meaning the value specified for delayTermination isn’t handled and no finishing tasks are executed.

false

disableDeepIdentification=<true/false>

Turns off Deep Identification. By default, the Agent recognizes how an application was launched (Spring Boot, Apache Tomcat, a plain Java application, or the Java Service Wrapper) and sends a small set of identifying values, so that Azul Intelligence On-Premises can show a meaningful application name instead of the main class of a launcher. With true, the Agent reports the main class only. This option is available in the Azul Intelligence Cloud Agent since version 1.3.0.

Azul Intelligence Cloud doesn’t use this data. If you don’t want the Agent to send it, set this option to true. See What Info is Transmitted for the values that are sent.

false

log=<level>

The level of logging for CRS. Options are (case insensitive): trace, debug, info, warning, error, off. The use of the trace level is discouraged, since this leads to enormous sized output.

If you want to see all messages logged by all services and monitors, you need to use, for instance, log=info to get all info messages. You can further extend the logged messages, by specifying the service or monitor. These are the available options:

  • args

  • connection

  • connection.pinger

  • id

  • inventory

  • mainMethod.detect

  • performance

  • requests.processor

  • service.classload

  • service.classloadevent

  • service.classload.loaderwrapper

  • service.classload.loaderlogger

  • service.event

  • service.filetailer

  • service.firstcall

  • service.gclog

  • service.heartbeat

  • service.jarload

  • service.jarload.ziptools

  • service.jarload.reporter

  • service.jfr

  • service.queue

  • service.systeminfo

  • service.upload

  • service.vmlog

  • service.vmtooling

  • utils

  • vmsupport

You can combine several configurations, for instance, log=info,log+connection=trace to get all info messages plus the trace messages related to the connection.

error

Usage Examples

 
# Environment variable for Azul Intelligence Cloud Agent
export JDK_JAVA_OPTIONS="-javaagent:${AGENTDIR}/ic-agent.jar=expression1,expression2,expression3 \
  -DaagentDir=${AGENTDIR} \
  -Djava.security.policy=${AGENTDIR}/agent.all.policy"

# Command line option for Azul JDK or JRE
java -XX:AzCRSArguments=expression1,expression2,expression3 \
  -jar MyApp.jar

# Environment variable for Azul JDK or JRE
export AZ_CRS_ARGUMENTS=expression1,expression2,expression3

How to Specify Configurations

Depending on how you run your Java applications to send data through the Forwarder to Azul Intelligence Cloud, several options are available to configure your runtimes.

Azul Intelligence Cloud Agent

For the Azul Intelligence Cloud Agent, both Tags and Arguments are configured with environment variables. Tags are defined with CRS_TAGS, while arguments are added in the agent configuration with JDK_JAVA_OPTIONS.

 
export CRS_TAGS={your_crs_tags}
export JDK_JAVA_OPTIONS="-javaagent:${AGENTDIR}/ic-agent.jar={your_crs_arguments} \
  -DaagentDir=${AGENTDIR} \
  -Djava.security.policy=${AGENTDIR}/agent.all.policy"

For example:

 
export CRS_TAGS="env.tag-1=value:1; env_Tag_2=value 2"
export JDK_JAVA_OPTIONS="-javaagent:${AGENTDIR}/ic-agent.jar=api.url=https://<FORWARDER_IP:PORT>,log=info \
  -DaagentDir=${AGENTDIR} \
  -Djava.security.policy=${AGENTDIR}/agent.all.policy"

Azul JDK or JRE Runtime

To enable and configure your instances running with an Azul runtime and CRS, you can choose to use one of these three options:

  1. JVM command line arguments

  2. The AZ_CRS_ARGUMENTS and CRS_TAGS environment variables

  3. A .properties file

The connected runtime looks for the configuration parameters in the order described above. You can use a combination of these options. If you set a parameter in several ways, for example via both the environment variable and configuration file, the JVM uses the value that comes first in the order given above.

In addition, the Forwarder address can be configured via DNS records. See Service discovery via DNS.

JVM Command Line Arguments

Pass configuration parameters to the CRS (Connected Runtime Service) in the Azul JVM by using the -XX:AzCRSArguments command line argument:

Minimal command that sets the api.url parameter via JVM arguments.:
 
java -XX:AzCRSMode=on \
    -XX:AzCRSArguments=api.url=https://<FORWARDER_IP:PORT> \
    MyApp
A more extended example via JVM arguments:
 
java -XX:AzCRSMode=on \
    -XX:AzCRSArguments=api.url=https://<FORWARDER_IP:PORT>,log=debug,delayTermination=120000,delayInitiation=0 \
    -Dcom.azul.crs.instance.tags={tags} \
    MyApp

Environment Variables

You can use dedicated environment variables to enable and control all JVM processes for Azul Zulu and Zing distributions. When the environment variables are present, they automatically apply to any newly started JVM, enabling CRS.

Substitute your forwarder_endpoint in the following example.

Starting with environment variables and optional arguments:
 
export CRS_TAGS={your_crs_tags}
export AZ_CRS_ARGUMENTS=enable,api.url=https://<FORWARDER_IP:PORT>,log=debug,delayTermination=120000,delayInitiation=0
java MyApp

Properties File

A third way to set the CRS parameters is to use a local .properties file. There are two default locations where CRS looks for the properties file, and you can specify a custom properties file as a command line argument. CRS looks for the properties file in the following order:

  1. the file provided via the -XX:AzCRSArguments=props=/path/to/config.properties argument

  2. ~/.az_crs/config.properties in the user’s home directory

  3. $JRE/lib/crs.properties, where $JRE is the directory where the JRE is located