Set up Agents

Depending on the technology to monitor and the operating system, initial setup varies. Some examples:

  • Host Agent and Web Server Master Agent bootstraps have .ini files in DT_HOME/agent/conf. Both are installed as services (Windows) or daemons (*NIX). The service needs to be uninstalled and reinstalled and the daemon's init.d/<shellScript> needs to be adapted if parameters like name or port change.
  • Classic Agents for Apache, IIS, and NGINX Web Servers, and PHP are slaves to the Web Server Master Agent and as such options like logfilesize, are configured by entries in its .ini.
  • The Agent for Java technologies can be configured with <option>=value appended to the configuration string, which is appended to java -options or a JAVA_OPTS variable in a Java configuration or start file.
  • For all Agents, environment variables named DT_<OPTION> (always capitalized) have the same effect as configuration string <options>, but are less flexible.
  • Configure .NET Agent options by choosing Start > Dynatrace > Dynatrace Agent Configuration for .NET tool, set directly in the registry or with environment variables, which take precedence if set.

Configuring Agents

Most arguments and options (<ArgParOrOptName>) have an environment variable equivalent (DT_<ArgParOrOptName>).

  • logfilesize is equivalent to DT_LOGFILESIZE.
  • name and agentname are equivalent to DT_AGENTNAME.

Environment variables are global, so setting one may affect other Agents. Also, there are different orders of precedence if you happen to have both the option and the environment variable set. For example, the environment variable for .NET precedes over the argument/parameter/option.

Mandatory arguments / parameters are applied in the following:

  • Connection string in the Java options.
  • .NET Agent Configuration Tool.
  • Web Server master Agent agent/conf/dtwsagent.ini.
  • Main Node.js JavaScript file. This must be the first lines at the beginning of the file to capture PurePaths.
  • Host Monitoring Agent agent/conf/dthostagent.ini.
Argument/Parameter=value ENVIRONMENT_VAR Comment
DT_AGENTNAME name is actually legacy, but used everywhere.
name <agentname> with a separating space in .ini.
Unquoted string according to variable-naming-rules.
If you opt for the environment variable, it must be DT_AGENTNAME.
Defines the Collector. Specify name or IP and optional port to connect to. The legacy server parameter stems from the Collector that was originally embedded in the AppMon Server.

The default port is 9998, or 8042 for HTTP. If no port is specified the default is used.

Based on scope and precedence, options are applied as environment variables if an environment variable is available for the respective option. If not available, the option is applied to the following:

  • Java options / connection string as <option>=<value>, no spaces and in any order as they are named.
  • .NET as registry keys.

For the Web Server Agent and Host/Infrastructure Monitoring Agent services/daemons only loglevel and logfilesize are exactly the same (names), so tech type = all in the table means Agent is started by the dtagent bootstrap. For all other Agents, see the specific page in the help for specific settings by Agent type.

Parameters for all tech types (Java, .NET, native)

The table lists options with corresponding environment variables, applicable for all tech types (Java, .NET, native)

Option=value ENVIRONMENT_VAR Default value Comment
logfile=<path>/name.log DT_LOGFILE <DT_HOME>/log/dt_<agentname>.<pid>.<index>.log It is important to specify the .log extension. The resulting name is <name>.<pid>.<index>.log.

Log rotation and log aging prevent the Agent from filling up the host's file system.
DT_LOGLEVELFILE info Log level in a log file.
Possible levels: none | off, finest, finer, fine, info, warning, severe.
DT_LOGLEVELCON info Log level on console.
Possible levels: none | off, finest, finer, fine, info, warning, severe.
logfilesize=<bytes> DT_LOGFILESIZE 10000000 Bytes (10MB) Value in bytes.
collectorlist=<path> DT_COLLECTORLIST <DT_HOME>/agent/conf/collectorlist.<tier><SystemProfile> Change default path if not writable.
debugflags=<list> DT_DEBUGFLAGS Comma-separated list of Agent debug flags.
sotimeout=<seconds> DT_SOCKTIMEOUT 30 Specifies the native Agent's socket timeout for sending/receiving data.
hirestimer=<type> DT_HIRESTIMER auto Sets the high-resolution timer that should be used for this Agent.

Possible types: cpu, os, java, runtime, auto.
storage DT_STORAGE DT_HOME/agent/downloads Points to AppMon home executables and to an agent/downloads subdirectory, where all configuration files, downloads, and log directories for Agents, as well as the core Agent are stored by the bootstrap part.

The bootstrap part of an Agent tries to save the core into a subdirectory agent/downloads to the following directories in the following order:
  • DTD_HOME (precursor of DT_HOME)
  • The path of the Agent, tmp, current directory. So having no environment variable set is fine because write permissions to agent/downloads are set at install time. If you did not install correctly and everything else fails, updates are still available.
wait=<seconds> DT_WAIT 20 Time the Agent waits for a connection to the Collector. Else uninstrumented.
environmentname=<string> Results in agentname[<environmentname>]
usessl=true|false DT_USESSL 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.

Tech-type specific options

Some options applied to selected technologies only.

Option=value Default value Comment
maxsamplingstackdepth=<#> 2048 Max stack depth that is captured in transactional snapshots.
maxsamplingmethodtablesize 65536 Max number of methods that are resolved. If this limit is reached the tables are cleared and all methods are resent again.
environmentdetection=<yes|no> yes Yes: The Agent tries to detect the environment context of the application server it is started in.

No: Prevents the Agent from trying to detect its environment if, for example, it detects a wrong application server.
transformationsamples=<# of samples> DT_TRANSFORMATIONSAMPLES 1333 Number of samples to take to determine slow transformation (classes).
transformationmaxavgwait=<milliseconds> DT_TRANSFORMATIONMAXAVGWAIT 60 Maximum average wait time for slow transformations.
ctimeout=<seconds> 10 Connection timeout—the time to wait to reconnect to the Collector in case of an interruption.
excludeclasses=<yes|no> yes Prerequisite for exclude.
exclude=<expression> A semicolon-delimited list of exclusion expressions. The expression has the following format: <match condition>:<class path>.

Excluded classes are not sent to the Collector for instrumentation. The excludeclasses option must be enabled.

The classname must be delimited by slash (/). The following example excludes classes that start with com.dynatrace.diagnostics.foobar and classes that contain the string Proxy in their name.
optionTestRunIdJava=<testRunId> GUID string Identify the test to be run with an ID obtained from a REST call for test automation.

Log rotation and aging

Log rotation and aging prevent the Agent from filling up the host's file system.

Log rotation

Each Agent limits its number of logs to 5, rotating the log file index. Because Index 0 contains environment and start up information, it is never overwritten. Each of these 5 files is limited to whatever logfilesize is configured as <option> passed to the JVM as described above.

Log aging

Because log file sizes and their number grow over time, the Agent purges logs files when:

  • A log file is older than 14 days
  • The combined size of all log files exceeds 1 GB of storage space
  • There are more than 1,000 log files

To prevent unnecessary delays in your application's start up, the Agent's bulk purge limit is set to delete a maximum of 50 of the oldest files. This logic is shared between bootstrap and core Agents, so in total 100 of the oldest files may be deleted at one time.