Web Server Master Agent configuration

Note

This page describes configuration of the Web Server Master Agent, thus relates to Classic Agent only. For information about technology-specific configurations, see one the following pages:

These Agents don't communicate with the Collector directly, but through the Master Agent.

The Web Server Master Agent dtwsagent[.exe] is in <DT_HOME>/agent/lib[64].

On Windows, the Agent is a service configured to auto-start at boot time.

On Linux and Unix, the Master Agent should be auto-started as a daemon. You should copy the <DT_HOME>/init.d/dynaTraceWebServerAgent shell script to or reference it (as a link) in /etc/init.d. Add the shell script to the system boot in chkconfig or update-rc.d, depending on your distribution. See also the isMasterAgentServiceInstalled setting below for another way to configure the Web Server Master Agent as a daemon.

Configure the Web Server Master Agent and slave Agents by adding settings in <DT_HOME>/agent/conf/dtwsagent.ini.

General settings

Setting Default Value Description
Port 8001 The UDP port on which the Web Server Master Agent should listen for data packets of the slave Web Server Agents. Change the port number only if the default port (8001) is used by a different application.

This is the port through which the salve Agents connects to the Master Agent, not for connection between Master Agent and AppMon Collector.
Name dtwsagent The name of the Agent, used for mapping it into the desired System Profile on the AppMon Server.
localhost:9998 localhost:9998 The AppMon Collector to which this Agent should connect. The address is of the form CollectorName[:port], for example [exampleCollector:9997](http://exampleCollector:9998)

This setting is called Server because in earlier releases the Collector was embedded in the AppMon Server. The embedded Collector is still available, but the standalone Collector must be used in all situations except for testing.
Loglevel info The log level. Valid values are 0 through 8, or finest | finer | fine | config | info | warning | severe | none.
ConsoleLoglevel none The console log level. Valid values are 0 through 8, or finest | finer | fine | config | info | warning | severe | none. Depending on this setting, log messages write to the console (or to the stderr output) as well as to the Agent log file.

For Apache, this log output can be also found in the Apache's error.log file.
LogfilePath <DT_HOME>/log The path to the directory that holds the log files.
LogfileSize 10 MiB The maximum log file size. As soon as a log file exceeds this limit, a new log file is created and the old one is saved. If no space is left on the device, logging is stopped until space is available. The maximum log file size must be greater than 64 KB.

The Master Agent and each of the slave Agents create their own log files. At any given time, at least two different log files exist. Specify the value as <size> [KiB|MiB].
SharedMemoryFileName <DT_HOME>/agent/conf/ dynaTraceWebServerSharedMemory The path to the file used for shared memory communication between Master Agent and slave Agents.
RemoveTag false Disables PurePaths tagging. If you set the RemoveTag value to true, the path correlation no longer works.

For example, use this setting in proxy environments, where different AppMon installations are running at the same time and you want to ensure that they do not interfere with each other.
NoBootstrap false If set to true, the Agent does not download the newest Agent DLLs and shared objects from the AppMon Collector, but instead uses the Agent located in the <dynatrace install dir>/agent/lib[64] directory.
usessl false Enables SSL encryption between the Master 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 Master Agent.

Compression of injected content and response overhead

If you get too much overhead through compression, switch it off with CompressInjectedResponse false in dtwsagent.ini. Compression may be handled by a load balancer.

For ASP.NET Applications also have a look at IISInjectionSpeedup in twsagent.ini. (description also in IIS Settings below) Changing this setting can reduce overhead for compression that you may otherwise see in the IIS.

Setting Default Value Description
CompressInjectedResponse true A browser may request HTML responses, where JavaScript Agent should be injected, in the compressed form, specifying it in the Accept-Encoding request header. This setting controls how the Web Server Master Agent handles such responses.

If CompressInjectedResponse is set to true (default), the response gets compressed as requested by a browser.

If it is set to false, the response is uncompressed, regardless of the Accept-Encoding specification. This can save some CPU load, but increases network traffic. Setting this to false makes most sense in scenarios with an HTTP load balancer in front of the Agent instrumentation that can take over the compression, along with the CPU load incurred by it.

This setting is meaningless if the JavaScript Agent instrumentation takes place elsewhere, for example at the backend application server.

IIS settings

This setting is only applicable for the IIS Agent

Setting Default value Description
IISInjectionSpeedup htm:always

html:always

aspx:never
The JavaScript Agent injection can be made faster for compressed requests by adapting request headers to postpone the compression until after the injection. The downside is a marginally slower performance for requests not yielding an injectable HTML.

Arguments: a comma-separated list of <extension>:<setting> where <setting> is one of the following: always, never, or auto. For unspecified extensions auto is the default, in which case a heuristic is applied to decide whether the compression should be deferred to after the injection.

aspx:auto is not recommended due to known to cause problems with script resources.
aspx:always is known to be incompatible with certain SharePoint components. If you don't use SharePoint you might want to consider setting aspx:always for a better performance of other aspx applications.


Example for the case when you don't use SharePoint: IISInjectionSpeedup htm:always,html:always,aspx:always

*NIX settings

These setting are applicable for *NIX platforms and have no relevance on Windows.

Setting Default value Description
isMasterAgentServiceInstalled false This setting is applicable for the Apache Agent only.

Controls how the Web Server Master Agent is started.

If set to false, the Apache Agent spawns a Web Server Master Agent process when starting. This is the default for background compatibility reasons.
If set to true (recommended), the Web Server Master Agent is controlled as a service or daemon independently of the Apache Agent.
SharedMemoryUnixFilePermissions 666 Use this directive to change the default permissions of the shared memory file. Use an octal value to specify the permissions. The default is 666, which means read and write rights for the owner, the group, and everyone.

Restart Master Agent

You can restart the Web Server Master Agent from the Client's Agent Overview / Status dashboard > Agent context menu.

Multiple instrumented web servers on one machine

There are two variants on Linux/Unix:

  • Deprecated legacy: The Master Agent is started by a slave Agent. The n\th slave tries to start another master with the same configuration and reverts to the first master after 30 seconds when it sees that the UDP port is already taken.
  • Preferred: The Master Agent is started as a daemon and the slaves connect on its UDP.

If your web server instances run different web sites and you want to have data for each web site in a separate System Profile:

  1. For every additional, differently named Web Server Master Agent, copy the Agent installation directory <DT_HOME>/agent to <DT_HOME><InstanceName>/agent.

  2. Make sure that the read/write permissions are the same for each folder after this step.

  3. Configure a unique UDP port (very first item in the .ini) and Agent name (and possibly a port on that the Collector listens) for each Web Server Master Agent instance in <DT_HOME><InstanceName>/agent/conf/dtwsagent.ini.

    Notes

    • How an Agent maps to an Agent Group in a System Profile defaults to a Starts comparison. The default Agent name in dtwsagent.ini is dtwsagent. If you call the second Web Server Master Agent dtwsagent2 and leave the comparison at Starts, the Agent maps into the same group.
    • The correct syntax for the Collector name and port is Server <CollectorName>[:port]. Supply a name, even if it´s localhost and only the port is different.
  4. Make sure to use the dtagent.dll or the libdtagent.so from the right copy of the Agent installation directory.

    • Windows: Install the additional Web Server Agent as an auto-starting service with <DT_HOME><InstanceName>/agent/lib/dtwsagent -service install -instance InstanceName
    • Linux or Unix: Install the additional Web Server Agent as an auto-starting daemon: cp <DT_HOME>/init.d/dynaTraceWebServerAgent /etc/init.d/dynaTraceWebServerAgentInstanceName
      In the shell script, adapt <DT_HOME> to point to the instance directory structure and add it to boot with chkconfig --add dynaTraceWebServerAgentInstanceName. Change the <DT_PIDFILE> variable in each of the copied shell scripts to point to different locations for the PID file so that one shell script does not overwrite the PID file of the other shell script.
      See also the isMasterAgentServiceInstalled setting above for another way of starting Web Server Master Agent.