Using the Azul Intelligence Cloud Agent
The Intelligence Cloud Agent is the prefered way to connect your Java Virtual Machine (JVM) with the Forwarder to send all the required data to your Intelligence Cloud instance. The Intelligence Cloud Agent is designed for wide compatibility and doesn’t conflict with natively-supported versions of the Azul JVM.
Provided Features
By using the Azul Intelligence Cloud Agent, your JVMs will send the required data to be able to use all the features provided by Intelligence Cloud.
Supported Platforms
The Azul Intelligence Cloud Agent is supported for Java 8 and newer and is independent of the Operating System or CPU architecture.
Installation
-
Download the latest version (1.3.0) of the Azul Intelligence Cloud Agent.
-
You can check ic-agent.json for a list of available downloads.
-
You can also download the agent from the Web UI > Settings > Agent.
-
-
Put the agent to an easy to locate directory on the systems where you run your Java applications, e.g.
/opt/azul-ic-agent/. In the following examples, this directory is referred as${AGENT_DIR}.
|
Note
|
The Azul Intelligence Cloud Agent has a minimal CPU overhead, but may consume up to 10% of your application’s memory usage. When configuring the maximum Java heap size (-Xmx<size>), account for this additional memory requirement.
|
Usage Instructions
Basic Usage
Export the following startup options on your runtime environment to attach the Intelligence Cloud Agent to your application.
export JDK_JAVA_OPTIONS="-javaagent:${AGENT_DIR}/ic-agent.jar=api.url=https://<FORWARDER_IP:PORT> \
-DaagentDir=${AGENT_DIR}"
|
Note
|
This will start the IC Agent on every start of the JVM. In case you are running your application and the Forwarder on the same machine, this approach is not recommended. |
You can configure the behavior of the agent further in detail, see CRS Tags and CRS Arguments with environment variables.
Advanced Usage
Configure Keystore
You can configure how the agent looks for the keystore certificates. When you specify keystore=<file_name> as an agent parameter, the agent will use the certificates from the given file. With the agent parameter keystorepassword=<value>, you can specify a password. See CRS Configuration Options > CRS Arguments for more information.
For example:
java -javaagent:ic-agent.jar=api.url=https://<FORWARDER_IP:PORT>,api.mailbox=default,log=info+stack+time,keystore=/<CERT_DIR>/<MY_CERT>,keystorepassword=<MY_PASSWORD> -jar <MY_APP>.jar
Configure Security Manager
Most Java applications do not use the SecurityManager, which was deprecated in Java 17. Some older applications that use the SecurityManager may need the following policy configuration:
grant codeBase "jar:file:${AGENT_DIR}/ic-agent.jar!/" {
permission java.security.AllPermission;
};
Check Your Setup
Since version 1.3.0, the Agent JAR can check your environment before you attach it to an application, or when the Agent doesn’t report. Run the self-diagnostic tool on the host of the application, as the same user, with the same Java runtime, environment variables and -D system properties as the application:
java -jar ${AGENT_DIR}/ic-agent.jar diagnose \
--agent_args="api.url=https://<FORWARDER_IP:PORT>"
Use the same option string as in your -javaagent option for --agent_args. You can also set individual Agent options with --<name>=<value>, and add --features=<list> (for example --features=JVMI,CI) to check that the local configuration allows the features you expect. Use --help to list all commands and options.
The tool checks, in this order:
-
Prerequisites: the Java version (Java 8 or newer), that the Agent isn’t already attached to the JVM of the tool (for example through
JAVA_TOOL_OPTIONS), the required JDK modules (java.managementandjava.instrument), and whether a SecurityManager is active. -
Configuration: the
-Dcom.azul.crs.*tweaks, the Agent options with their origin, the feature flags, and the tags. -
Connection: that
api.urlis valid, and that the Forwarder can be reached, through the same proxy and TLS setup as the Agent. When this fails, the tool names the failing layer (DNS, TCP, timeout, proxy, host name, certificate, or TLS) and gives a hint. It also warns when the certificate of the Forwarder expires within 30 days, or when plain HTTP is used.
Each check reports PASS, WARN or FAIL with a one-line summary and a hint for every problem. The report ends with the overall result and the -javaagent option to add to the start command of your application.
| Exit code | Meaning |
|---|---|
|
All checks passed. |
|
At least one warning. |
|
At least one failure. |
|
The tool stopped: Java older than 8, the Agent is attached to the JVM of the tool, or invalid tool arguments. |
The tool is safe to run in production. It changes nothing, and sends no telemetry or application data. Its only network traffic is one connection request to the Forwarder, without authentication. It never prints secrets, such as access keys and passwords: these are shown as <hidden>, so you can share the output with Azul support.
Limitations:
-
The tool can’t see the running application. When you don’t pass the same options and
-Dproperties, or run it as another user or with another JDK, the results can differ from the real Agent. -
It doesn’t check the authentication against the service, the host for artifact uploads, or a SecurityManager or proxy selector that the application installs at runtime.
-
In containers, run the tool inside the container, for example with
docker execorkubectl exec, and with the JDK of the application. -
When the network is slow, the connection check can take up to 50 seconds.
-
The
-javaagentoption at the end of the report is quoted for a POSIX shell. On Windows, the quoting may need adjusting.
For an example with sample output, see Diagnosing Problems in the Azul Intelligence On-Premises setup.