Java Agent
Java Agent Integration
A Java agent is a JAR application that starts together with the Java Virtual Machine and can instrument or monitor the main application. The platform lets you attach a custom agent by uploading its JAR file and adding the -javaagent JVM option.
Java Agent Overview
A Java agent is loaded by the same JVM and class loader as the application and runs under the same security rules and runtime context. Agents are commonly used for application monitoring, tracing, profiling, diagnostics, data collection, and bytecode instrumentation.
JVM startup option
The agent is activated through the -javaagent:/path/to/agent.jar option. Because this option is processed during JVM startup, the application-server nodes must be restarted after the configuration is changed.
Upload the Agent JAR
Open Configuration Manager
Sign in to the platform dashboard and click Config beside the required Java application-server layer.
Select an upload directory
Open the application-server home directory or another location that is preserved by the selected stack.
Upload the JAR file
Use the Upload action to select the Java agent JAR from the local computer or provide a direct file URL.
Multi-node environments
Upload the agent JAR to every application-server node that must run the agent, or use a synchronized storage and deployment method that keeps the same path available on all nodes.
Configure the -javaagent Option
For Tomcat, TomEE, and Jetty, open the variables.conf file in the application-server server configuration folder and add the agent option with the absolute path to the uploaded JAR.
-javaagent:/absolute/path/to/my-java-agent.jar
Some agents accept optional arguments after an equals sign:
-javaagent:/absolute/path/to/my-java-agent.jar=option1=value1,option2=value2
Use the agent documentation
The exact arguments, configuration properties, network endpoints, credentials, and log settings depend on the selected agent. Add only the options documented by the agent provider.
Application-Server Paths
The following paths are commonly used when the agent is uploaded to the application-server home directory:
| Application Server | Example Agent Path | Configuration Method |
|---|---|---|
| Tomcat / TomEE | /opt/tomcat/temp/my-java-agent.jar |
Add -javaagent to variables.conf. |
| Jetty | /opt/jetty/home/my-java-agent.jar |
Add -javaagent to the stack’s JVM options or variables configuration. |
| GlassFish | /opt/glassfish3/temp/my-java-agent.jar |
Open the GlassFish administration panel and add the option under JVM Settings → JVM Options. |
GlassFish Configuration
For GlassFish, open the administration panel, select the appropriate server or cluster configuration, and add the full -javaagent option under JVM Settings → JVM Options.
Restart and Verify the Agent
Save the configuration
Save variables.conf or the GlassFish JVM configuration after adding the agent option.
Restart the application-server layer
Use Restart Nodes for the affected application-server layer so the JVM starts with the agent attached.
Review startup logs
Open the application-server and agent logs. Confirm that the agent JAR was found, loaded successfully, and connected to any required external service.
Expected Result
The application-server JVM starts with the uploaded Java agent. The agent runs in the same JVM as the application and performs its configured monitoring, tracing, profiling, or instrumentation tasks.
Important Notes
- Use an agent version compatible with the installed JDK and application server.
- The JAR path must be absolute and must match the actual upload location.
- Restart the affected application-server nodes after changing JVM options.
- Apply the same agent configuration to every node in a scaled layer.
- Monitor CPU, memory, startup time, and application latency after enabling an agent.
- Protect any API keys, tokens, or credentials required by the agent.
- Remove or comment out the
-javaagentoption if the agent prevents the server from starting.
Common Issues and Solutions
| Issue | Solution |
|---|---|
| Server fails to start | Check the agent path, JAR integrity, JDK compatibility, and JVM startup logs. Temporarily remove the option to restore service. |
| Agent is not visible in logs | Confirm that the nodes were restarted and that the option was added to the JVM settings used by the running process. |
| Only one application node reports data | Upload and configure the agent on every node in the application-server layer. |
| Agent cannot connect to its service | Review endpoint URLs, credentials, proxy settings, DNS, outbound firewall rules, and TLS configuration. |
| Application performance decreases | Reduce agent instrumentation, sampling, or logging according to the agent provider’s documentation. |