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.

Note

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
name=<AgentName>
or
agentname=<AgentName>
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.
collector=<CollectorName>[:port]
or
server=<CollectorName>[:port]
DT_COLLECTOR
or
DT_SERVER
Defines the Collector. You 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> DT_LOGFILE <DT_HOME>/log/dt_<agentname>.<pid>.#.log1
loglevel=<level> or loglevelfile=<level> DT_LOGLEVELFILE info Log level in a log file.
Possible levels: none | off, finest, finer, fine, info, warning, severe.
loglevelcon=<level> or logstdout=<level> 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 AgentDebugFlag=value
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. 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 the all configuration files, downloads, and log directories for Agents, as well as the core Agent are stored by the bootstrap part.2
wait=<seconds> 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.

1 Log rotation and log aging prevent the Agent from filling up the host's file system.
2 The bootstrap part of an Agent tries to save the core into a subdirectory agent/downloads to the following directories in the following order:

  • DT_STORAGE
  • DT_HOME
  • 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.

Options for certain tech types

Some options applied to selected technologies only.

Options for Java

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 — time to wait to reconnect to the Collector in case of an interruption.
excludeclasses=<yes|no> yes Prerequisite for exclude.
exclude=<expression> not set semicolon-delimited list of <match condition>:<class path>.1
optionTestRunIdJava=<testRunId> GUID string Identify the test to be run with an ID obtained from a REST call for test automation.

1 Excluded classes are not sent to the Collector for instrumentation.
excludeclasses needs to be enabled (default).
The classname must be delimited by slash '/'. For example:
-agentpath:...,exclude="starts:com/dynatrace/diagnostics/foobar;contains:Proxy" excludes classes that start with com.dynatrace.diagnostics.foobar and classes that contain the string Proxy in their name.
More examples:
exclude="starts:java/util/LinkedHashMap;contains:LinkedHashMap;ends:HashMap"
Quotes are optional, for example:
exclude=ends:MyImpl

Options for .NET

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.
disableperfcounters=true|false=not set DT_DISABLEPERFCOUNTERS not set Add a key disableperfcounters value true in HKEY_LOCAL_MACHINE\SOFTWARE\dynaTrace\Diagnostics\Agent\whitelist\&lt;num&gt;.
DT_TESTRUN_ID=<testRunId> GUID string Identify the test to be run with an ID obtained from a REST call for test automation.

Options for Native

Option=value Default value Comment
perfcounterinterval=<multiples_of_10_secs> DT_PERFCOUNTERINTERVAL 10 Perfcounter poll interval.
enablenetworkdrivemonitoring=<true|false> false Network drive monitoring is by default disabled on Windows.
disablewifiadaptermonitoring=<true|false> false
overridehostname=<host name> not set | empty string Overrides the auto detected host name with the specified value.
buffers=<# of event buffers> 100000 Number of event buffers to allocate. This only works when profile does not already set non-default.

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.