Java Agent configuration

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.
  • server or 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 optionName=value.

Note

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:
-agentpath:<agentlib>=<parameter>[,<option>]

Note

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:

`-agentpath:/opt/dynatrace-7.0/agent/lib64/libdtagent.so=name=Java_mySystemProfile,collector=localhost`

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
Note

When adding the agentpath to a wrapper.conf file, you must use frontslashes (/) in the path to the dtagent.dll.

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.

Parameter Description
name=<agentname> 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 (mySystemProfile in the previous example).

The agentname must be unique among all deployed Agents and must not contain spaces, tabs, commas or other special characters.
collector=<host>[:port]
or
server=<host>[:port]
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 Server stems from past releases when the Collector was Server-integrated. Most licenses allow only standalone Collectors, except for testing.
loglevel=<level> Optional: Specifies the overall log level. The level can be one of the following: finest | finer | fine | config | info | warning | severe | none. When the loglevel option is omitted, the level defaults to info.
logstdout=<level> 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: finest | finer | fine | config | info | warning | severe | none. When the logstdout option is omitted, the level defaults to info.
logfile=<filename> Optional: Specifies the filename of the logfile. If omitted, the filename defaults to <dt_agentname_pid.log>.
logpath=<path> Optional: Specifies the target path to write the log files. If omitted, the logpath defaults to ../../log relative to the location of the native agent library.

Make sure that the directory is writable for the application process.
hirestimer=<timertype> Optional: This option sets the high-resolution timer you must use for this Agent. The timertype is one of the following values: cpu | os | java | runtime | auto. When the hirestimer option is omitted or set to auto, the timertype defaults to the best option for your platform.
wait=<seconds> 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.
sotimeout=<seconds> Optional: Specifies the native Agent's socket timeout to send and/or receive data in seconds. Defaults to 30 seconds.
ctimeout=<seconds> Optional: Specifies the maximum time that the native Agent waits until a connection to the AppMon Server is established. Default is 10 seconds.
tmtimeout=<milliseconds> Optional: If specified, AppMon issues a warning log message if the transformation of a single class exceeds the specified time.
transformationmaxavgwait=<milliseconds> 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.
overridehostname=<custom hostname> Optional: This flag disables the auto detection of the hostname. It overrides the equivalent option in an agent configuration .ini file.
optionTestRunIdJava=<testRunId> Identify the test to be run with an ID obtained from a REST call for test automation.
enforcepci=true|false 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.
usessl=true|false 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 true before launching the Agent.

Environment variables

The use of DT_HOME is optional.

If set, <DT_HOME> should refer to the AppMon installation directory. With a default full installation:

  • On Windows, %DT_HOME% should point to %ProgramFiles%\Dynatrace\Dynatrace 7.0
  • On *NIX, if you change to the opt directory (cd /opt) before installation as recommended, $DT_HOME should point to /opt/dynatrace-7.0.

If specifying the Agent path, you only need to put dtagent as <agentlib>. Path statements are:

  • Windows: set PATH=%PATH%;%DT_HOME%\agent\lib[64].
  • *NIX: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$DT_HOME/agent/lib[64] Use export for bash or setenv for csh.

Debugging and agent conflicts

When enabling debugging, the Agent conflicts with jdwp tools. To prevent this, use the Java option:

`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=10284`

instead of

`-Xdebug`

`-Xrunjdwp:transport=dt_socket,address=10284,server=y,suspend=n`  

AppMon Agent usage

If you're using AppMon Agent, don't forget to configure ports for it.

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.