Installing the Agent

Supported Platforms

The Agent runs on Java 8 and newer, and is independent of the operating system and CPU architecture. On Java 6 and 7, the Agent prints Azul IC Agent requires 8+ java runtime to run to the standard error output and doesn’t start. Your application runs normally.

Downloading the Agent

Attaching the Agent

Agent options have the form <name>=<value> and are separated by commas. Replace <FORWARDER_HOST>:<PORT> with the address of your Forwarder. Use these options:

You can pass the options in two ways.

On the command line, append the options to the -javaagent option of your application:

 
java -javaagent:${AGENT_DIR}/ic-agent.jar=api.url=http://<FORWARDER_HOST>:<PORT>,noSsl=true,notifyJarLoad=false,notifyClassLoad=false,sendCRSLogs=false,delayTermination=60000 -jar <MY_APP>.jar

In the AZ_CRS_ARGUMENTS environment variable, set the same options in the environment of your application, and start it with -javaagent alone:

 
export AZ_CRS_ARGUMENTS="api.url=http://<FORWARDER_HOST>:<PORT>,noSsl=true,notifyJarLoad=false,notifyClassLoad=false,sendCRSLogs=false,delayTermination=60000"
java -javaagent:${AGENT_DIR}/ic-agent.jar -jar <MY_APP>.jar

When an option is set in both places, the command line wins. Values can’t contain a comma. Anyone who can read the environment of the process can read the variable, so don’t put passwords into it. See the Agent documentation for all options and for the properties file.

 
export JAVA_TOOL_OPTIONS="-javaagent:${AGENT_DIR}/ic-agent.jar=api.url=http://<FORWARDER_HOST>:<PORT>,noSsl=true,notifyJarLoad=false,notifyClassLoad=false,sendCRSLogs=false,delayTermination=60000"

Choosing HTTP or HTTPS

The Forwarder serves either HTTP or HTTPS on its port, not both, so your Agents and AMT use the same one. AMT supports both, see Choosing HTTP or HTTPS for AMT.

HTTPS is the default and the recommended setup, described below. HTTP is a deliberate opt-out for a network you trust. The examples on this page use it because it needs no certificate: set noSsl=true and use an http:// address. Without noSsl=true, the Agent refuses an http:// address. The Forwarder must serve plain HTTP as well, and Agent versions older than 1.3.0 support HTTPS only. With plain HTTP, all observations travel unencrypted on your network, so use plain HTTP only on networks you trust.

HTTPS is supported by the Agent, the Forwarder, and AMT. You provide the security of this connection: you obtain and manage the certificate that the Forwarder presents, issued for its host name, and the Agent verifies it. There is no option to keep HTTPS on and skip that verification. When a CA in the default truststore of the JVM issued the certificate, the Agent needs no extra option. When your own internal CA issued it, put the CA certificate into a JKS keystore and point the Agent at it with keystore=<FILE> and keystorepassword=<PASSWORD>, and use an https:// address without noSsl. See Choosing HTTP or HTTPS for the Forwarder side.

 
java -javaagent:${AGENT_DIR}/ic-agent.jar=api.url=https://<FORWARDER_HOST>:<PORT>,notifyJarLoad=false,notifyClassLoad=false,sendCRSLogs=false,delayTermination=60000,keystore=${AGENT_DIR}/forwarder-trust.jks,keystorepassword=<MY_PASSWORD> -jar <MY_APP>.jar

Adding Tags

You can tag a JVM on the Agent. Tags are optional. See Tagging Your JVMs for the tag format.

Set the tags as <name>=<value> pairs separated by semicolons, in one of two ways.

In the CRS_TAGS environment variable of your application:

 
export CRS_TAGS="AppEnv=OrderService.default.prod.region1;team=payments"

In the com.azul.crs.instance.tags system property, on the command line of your application:

 
java -Dcom.azul.crs.instance.tags="AppEnv=OrderService.default.prod.region1;team=payments" \
     -javaagent:${AGENT_DIR}/ic-agent.jar=api.url=http://<FORWARDER_HOST>:<PORT>,noSsl=true,notifyJarLoad=false,notifyClassLoad=false,sendCRSLogs=false,delayTermination=60000 \
     -jar <MY_APP>.jar

In a shell, quote the value, because the semicolon ends a command. When both set the same tag, the system property wins.

Diagnosing Problems

When the Agent doesn’t start or can’t connect to the Forwarder, run its self-diagnostic tool on the host and as the user of your application, with the application’s Java runtime, its system properties, and the same Agent options:

 
java -jar ${AGENT_DIR}/ic-agent.jar diagnose \
     --agent_args="api.url=http://<FORWARDER_HOST>:<PORT>,noSsl=true,notifyJarLoad=false,notifyClassLoad=false,sendCRSLogs=false,delayTermination=60000"

The tool checks the Java runtime, the Agent options, and the connection to the Forwarder. It reports each check as PASS, WARN, or FAIL with a hint, and ends with the -javaagent option to add to your application. It sends no data. In this example, the Agent reaches a Forwarder that serves plain HTTP:

 
Azul Intelligence Cloud agent diagnose (a-agent 1.2.9)

Prerequisites (can the agent start in this JVM?)
[PASS] Java version          Debian 17.0.20.1
[PASS] Agent already loaded  no agent attached to this JVM
[PASS] JDK prerequisites     java.management, java.instrument present
[PASS] SecurityManager       not active

Configuration
[PASS] Tweaks                no tweaks set
[PASS] Agent options         6 set
                             set:
                               delayTermination=60000 (command line)
                               notifyJarLoad=false (command line)
                               notifyClassLoad=false (command line)
                               noSsl=true (command line)
                               sendCRSLogs=false (command line)
                               api.url=http://<FORWARDER_HOST>:<PORT> (command line)
                             adjusted by the agent:
                               notifyFirstCall=false: depends on notifyClassLoad, which is disabled
                             properties file:
                               none (looked in /home/app/.az_crs/config.properties, /usr/lib/jvm/java-17-openjdk-amd64/lib/az_crs.properties)
[PASS] Feature flags         allowed locally: JVMI; not allowed: CI
[WARN] Tags                  no tags set: 1 missing AppEnv
                             problems:
                               AppEnv: missing
                                 hint: set it, e.g. -Dcom.azul.crs.instance.tags="AppEnv=prod" or CRS_TAGS=AppEnv=prod; without it the application lands in the default environment

Connection
[WARN] Forwarder connection  http://<FORWARDER_HOST>:<PORT> reachable (HTTP 200, 17 ms)
                             problems:
                               api.url=http://<FORWARDER_HOST>:<PORT>: http:// with noSsl: the agent's token and data aren't encrypted
                                 hint: use https:// and remove noSsl
                             connection:
                               endpoint: http://<FORWARDER_HOST>:<PORT>
                               route: DIRECT

Result: WARN (2 warnings), exit code 1

To start the application with the agent, add to its java command:
-javaagent:/opt/azul-ic-agent/ic-agent.jar=api.url=http://<FORWARDER_HOST>:<PORT>,noSsl=true,notifyJarLoad=false,notifyClassLoad=false,sendCRSLogs=false,delayTermination=60000

With plain HTTP, the Forwarder connection check always reports WARN, because the traffic isn’t encrypted. That is expected when you have chosen plain HTTP on a trusted network. The WARN of the Tags check about the missing AppEnv tag doesn’t stop the Agent. Azul Intelligence On-Premises keeps the tags you set, and we recommend setting AppEnv to the application and its environment when you first deploy the Agent. See Tagging Your JVMs.

See Check Your Setup in the Agent documentation for all options, the exit codes, and the limitations of the tool.

Configuring the Security Manager

Most Java applications don’t use the SecurityManager, which is deprecated since Java 17. An application on an older Java version that runs with a SecurityManager may need a policy that grants the Agent its permissions, for example:

 
grant codeBase "jar:file:${AGENT_DIR}/ic-agent.jar!/" {
  permission java.security.AllPermission;
};

Reading the Agent Log

The Agent logs locally to the standard error output of your application. Every line starts with the [CRS prefix, for example the line that the Agent logs at startup:

 
[CRS.id][info] com.azul.crs.javaagent.client.Agent002.init: Azul IC Agent <VERSION> (<REVISION>) started with args='api.url=...' and enabled accessor.

Control the log level with the log option, for example log=debug. See the Agent documentation for all logging options.