The Java Agent uses the JVM Tool Interface. To configure it, you need to pass parameters to the Java Virtual Machine. You can do it using the command line (for example
java -<option> -jar <jarfile>), add the required parameters to an
.ini file or to the JAVA_OPTS variable in a configuration or start file, such as
setenv.sh or a batch file.
Three parameters are mandatory:
agentpath: the directory where the agent is installed.
name: the name of the Agent.
collector: The Collector to which the Agent connects.
In addition you can add options, listed in the table below. Options are separated with a comma, contain no spaces in between and can be in any order with the syntax
For AppMon 6.3.4 and later, there is an important new security setting
enforcepci for PCI-compliance.
The generic syntax for J2SE 6.0 and later is as follows:
Java versions earlier than 6.0 are not supported.
For Linux, to instrument a Java application with a default installation of AppMon, all on one machine and all 64-bit, and the Agent mapping into the
mySystemProfile, add the following:
For Windows, add the following:
`-agentpath:C:\Program Files\dynaTrace\dynaTrace 7.0\agent\lib64\dtagent.dll=name=Java_mySystemProfile,collector=localhost`
Agent configuration for Java-based application servers
The configuration string for the Java Agent is very similar for all platforms using Java, but there are some differences where and in what dialog box or file to place it. See the related topics on this page for links to configuration string information for supported Java-based application servers.
Agent Configuration for Java-based Windows Services
The configuration string is similar for Windows services implemented in Java, but the configuration mechanism is different. These services typically start using
wrapper.exe, which uses a
wrapper.conf file to pass in Java options. The following is an example of adding a parameter to start the Agent:
# Java Additional Parameters #wrapper.java.additional.1= wrapper.java.additional.1=-agentpath:C:/Program Files/dynaTrace/dynaTrace/agent/lib64/dtagent.dll=name=Java_mySystemProfile,collector=localhost:9998
When adding the
agentpath to a
wrapper.conf file, you must use frontslashes (
/) in the path to the
Parameters and options
The following table lists and describes parameters and options of the Java Agent. All items can not only be passed as connection string arguments, but also expressed as environment variables. For example,
DT_LOGLEVEL is functionally similar to
loglevel, but less flexible, since it applies to all components on one machine.
See Application Integration for examples and details of parameter usage on various application servers.
||Mandatory: Assigns a descriptive name to the Agent. The name should reflect the tier (here: Java) or application that the agent observes, possibly concatenated with _SystemProfileToMapInto (
The agentname must be unique among all deployed Agents and must not contain spaces, tabs, commas or other special characters.
|Mandatory: Defines the Server-embedded or stand-alone Collector. It sets the host, and optionally, the port to which the Agent connects. The host may be a (fully qualified) host name or an IP Address. The port defaults to 9998.
The argument name
||Optional: Specifies the overall log level. The level can be one of the following:
||Optional: Specifies the log level to write to the console. When you set this option to NONE, it suppresses all log output to console, but still writes to the log file. The level is one of the following:
||Optional: Specifies the filename of the logfile. If omitted, the filename defaults to
||Optional: Specifies the target path to write the log files. If omitted, the logpath defaults to
Make sure that the directory is writable for the application process.
||Optional: This option sets the high-resolution timer you must use for this Agent. The
||Optional: Specifies the initial wait timeout — the maximum time to wait for a connection to an AppMon Collector in seconds. If the connection cannot be established within this timeframe, the application continues uninstrumented. Defaults to 20 seconds now; was 60s until 5.5.
Note AppMon Collector often referred to as Server (also in Client dialog boxes), because the Collector was integrated in the AppMon Server. You can still use the Server-embedded Collector to save memory when you test AppMon, but the standalone Collector is enforced (with the license) in real-world scenarios.
||Optional: Specifies the native Agent's socket timeout to send and/or receive data in seconds. Defaults to 30 seconds.|
||Optional: Specifies the maximum time that the native Agent waits until a connection to the AppMon Server is established. Default is 10 seconds.|
||Optional: If specified, AppMon issues a warning log message if the transformation of a single class exceeds the specified time.|
||Optional: If the average class transformation time (based on the first 1333 transformed classes) exceeds this timeout, the instrumentation stops, but the Agent stays connected, and resource dumps are possible. Defaults to 60 milliseconds.|
||Optional: This flag disables the auto detection of the hostname. It overrides the equivalent option in an agent configuration
||Identify the test to be run with an ID obtained from a REST call for test automation.|
||Prevents capturing of security/privacy relevant info (method arguments and memory dumps) directly on the Agent, meaning it cannot be changed on the Client.
For AppMon 6.3.4 and later, the default is false. For PCI-compliance set this to true.
||Enables SSL encryption between the Agent and the Collector. Encrypted communication uses the same port as non-encrypted. To enable SSL you need to set this parameter as
The use of DT_HOME is optional.
<DT_HOME> should refer to the AppMon installation directory. With a default full installation:
- On Windows,
%DT_HOME%should point to
- On *NIX, if you change to the
cd /opt) before installation as recommended,
$DT_HOMEshould point to
If specifying the Agent path, you only need to put
dtagent as <agentlib>. Path statements are:
exportfor bash or
Debugging and agent conflicts
When enabling debugging, the Agent conflicts with
jdwp tools. To prevent this, use the Java option:
AppMon Agent usage
This agent is available in both multiple agent platforms. Please check the release status of the agent before switching over as some agents are still in BETA.