Install collectors

This page details installing Collector instances and covers critical information needed before installation. It also covers starting and stopping a Collector, embedded Collector restrictions, and troubleshooting.

What to know before installing collectors

*NIX

  • For AppMon 6.3 and later, reworked init.d shell scripts allow Collectors (and the Server) to start as non-root or under the desired user account.

  • If your Linux uses systemd for startup, see the attached systemd script samples (wrappers for init.d).

  • The installation requires Java Runtime Environment (JRE) 1.8 or later. Because the Unix installer does not include the private JRE for Collector run time (Windows and Linux do), you should update your system's public JRE to 1.8 first, as that is required for the Collector run time.

  • Some Linux flavors come with low limits for the maximum number of files, sockets, and processes or threads per user (1024). This normally poses no problem for the AppMon Collector. However, if running several of them within one user account and a couple of dozen Agents are connected to each Collector, raise both settings. Some Linux Operating Systems have limits of 64k, so stay on the safe side for situation such as a high number of Agent Groups. Increase low limits generously with this formula:

    (500) + (3 * number of Agents connected) * (number of Collectors running on account)

  • Check limits before setting them too low or lower than they were, which could harm your system.

  • Check hard limits (and set them) to account for desired soft limits, as soft limits cannot exceed hard limits. Permissions are required.

  • Set limits permanently for daemons in /etc/security/limits.conf. See an explanation in that file for more information.

    Per User Check hard limit Check soft limit Set soft limit on the fly
    files/sockets ulimit -Hn ulimit -n ulimit -n <numberToSet>
    processes/threads ulimit -Hu ulimit -u ulimit -u <numberToSet>

    You can force a check for 2048 at Collector-startup with the -openfiles parameter, but be aware that several run under the same user.

All platforms

  • A Collector should always be placed close (in terms of latency) to the connected Agents. There are thousands of start-up round-trips between them to instrument application classes. A Collector should be placed in the same sub-net, or at least in the same data center as the Agents and instrumented applications. This allows connecting to the AppMon Server over the WAN if needed.

  • The number of Collectors is not the exclusive sizing factor, but also JVM heap memory and the number of cores (and naturally disk space) available to a Collector process determines the number of Agents it can take. Also, Collectors need a lot more heap and disk space (for class cache and inheritance map) if the instrumented applications are different, so applications should be hooked to Collector groups according to their similarity. Sensible grouping of apps and equally sized Collectors in a group are also prerequisite for Collector - Agent load balancing. See Collector Best Practices to adapt settings when your requirements change or ask sales or support.

Install collectors

Windows

Download the full Windows installation package for your architecture. Do a custom installation if you only need the Collector.

The setup defaults to an installation path (%DT_HOME>) of C:\Program Files\Dynatrace\Dynatrace 7.0.

Installation creates Start menu entries and registers an auto-starting Windows service, configured to connect to an AppMon Server on the same machine (localhost) on the default port (6698 or 6699 (SSL)) and name (AppMon Collector 7.0).

*NIX

Do not run the AppMon Collector as root

Run the installation using a designated account. For AppMon 6.3 and later, you can define DT_RUNASUSER in the script.

Download the AppMon Collector installation JAR file. The Linux Collector installation file is named dynatrace-collector-<version>-linux-x86.jar, implying 32-bit on the x86 platform if you look at the other namings, but contains both bitnesses.

On Linux, the installer prompts for bitness (32-bit or 64-bit) and for the installation directory, which defaults to <currentDirectory>/dynatrace-collector-7.0. This path is referred to as <DT_HOME>.

If installing on Solaris, HP-UX, AIX, z/Linux, or z/OS, the installer prompts you for JAVA_HOME, which specifies the Java installation used to run the AppMon Collector. The Linux version comes with a private JVM.

The recommended installation is in /opt. Start the installation by issuing:

cd /opt
sudo java -jar <path>/dynatrace-collector-<version>-<platform>.jar
sudo chown -R <DT_RUNASUSER>:<DT_USER'SGROUP> /opt/dynatrace-<version>

Copy the dynaTraceCollector shell script to /etc/init.d.
Define DT_RUNASUSER in the script. You can also define other variables like DT_OPTARGS and DT_INSTANCE if necessary.
Add this script to the system boot by using chkconfig --add dynaTraceCollector or, depending on your distribution, such as on Debian or Ubuntu, use sudo update-rc.d dynaTraceCollectorNonRoot defaults.

Note

If you do not specify a DT_RUNASUSER, then register the script and restart, the Collector starts in the root. This means <DT_HOME>/collector/osgi and temp belong to the root. To correct this, rerun the chown command.

Check if dtcollector not work on your Linux flavor, try ps aux|grep dtcollector. The first, short output is for the launcher and the second, long one is for the Collector. The third one is for grep.
The user the Collector runs under is at the very beginning, before the PID.

Install extra collector instances

All operating systems

The Collector names (Windows: service names) and the port each Collector listens for Agents must be unique.

If you want your Collector instance to connect to a specific Server other than localhost, add -server <dynaTraceServerName> to the registration (Windows) or shell script (Linux/Unix).

The first start of the new Collector instance creates the directory structure <DT_HOME>\collector\instances\<CollectorInstanceName> that replicates the structure of the default instance and copies the files from there.

Windows

This sample code shows how to register and start a new service called Dynatrace Collector 7.0 (MyCollector) that listens for Agent connections on port 9997:

CD %DT_HOME%
dtcollector -service install -instance MyCollector -listen :9997
sc start "Dynatrace Collector  (MyCollector)"

To register an extra Collector service instance that listens for Agents on port 9997 and connects to myAppMonServer (on a different machine):

dtcollector -service install -instance MyCollector -listen :9997 -server myAppMonServer

To un-register a Collector instance, for example (to possibly re-register it with new arguments):

sc stop "Dynatrace Collector 7.0 (MyCollector)"
sc delete "Dynatrace Collector 7.0 (MyCollector)"

or

%DT_HOME%/dtcollector -service uninstall -instance MyCollector

Linux and Unix

The following sample code prepares and starts a Collector instance collector02 that listens for Agent connections on port 10001 and connects to a Server on the same machine on the default port (6698).

cd $DT_HOME
./dtcollector -instance collector02 -listen :10001

To start the collector02 instance at system startup, copy the $DT_HOME/init.d/dynaTraceCollector shell script, for example using Save As to create the flle /etc/init.d/dynaTraceCollector02. Make the following minimum changes:

DT_OPTARGS="-instance collector02"
DT_INSTANCE=collector02

Be sure the <instanceName> in DT_INSTANCE and DT_OPTARGS="-instance <instanceName>" are the same.
Add the script to the startup items by using /sbin/chkconfig &dash;-add dynaTraceCollector02 (or the chkconfig equivalent on your distribution).
Check for running Collectors by using ps ax | grep dtcollector.

Installed directories

This table lists directories of special interest created when installing a Collector.

Relative path Description
DT_HOME The executables and the main configuration file dtcollector.ini.
DT_HOME\log\collector Log files.
DT_HOME\collector\cache Class cache directory.
DT_HOME\collector\conf Main configuration directory.

Collector fail-Over / Agent connection balancing

See Collectors > Collector Groups for Connection-Balancing and Fail-Over for details.

Embedded collector usage restrictions

The AppMon Server includes an embedded (as opposed to stand-alone) Collector that should only be used for testing purposes. The embedded Collector is started in-process with the Server, a stand-alone Collector service / daemon must be explicitly started. Enable the embedded Collector in the Client by selecting Settings > Dynatrace Server > Services and selecting the Allow Agent Connections to Dynatrace Server check box under Embedded Collector Settings. You must restart the AppMon Server after changing this setting.

The table indicates whether the embedded Collector can (Check) or cannot (Cross) be used by different AppMon editions in different (license) scenarios.

Edition or
Installation type
Production Pre-production (aka Test Center) Dev team
(discontinued)
POC Check Check Check
Evaluation Check Check Check
Perpetual Cross Cross Cross
Term Cross Cross Cross

Start and stop a collector

Windows

On Windows, you can control the AppMon Collector from the Start menu, command line, or Services control panel. The registered service name is Dynatrace Collector <version> [(<instanceName>)].

For example, to start the Collector, execute:

sc start "Dynatrace Collector 7.0"

To configure the service to start automatically on system startup, execute:

sc config "Dynatrace Collector 7.0" start= auto

There is no space between start and =, but there must be a space after start=.

Alternatively, you can start the Collector from the command line:

cd %DT_HOME%
dtcollector.exe -service start

See Extra Instances on Windows to start or stop more than one Collector instance on one machine.

*NIX

For testing purposes, you can interactively start the AppMon Collector in the background (-bg) by using the launcher dtcollector. The following commands start a Collector that listens on localhost for Agents on default port 9998 and connects to an AppMon Server at default port 6698:

cd $DT_HOME
./dtcollector -bg

You can use <DT_HOME>/init.d/dynaTraceCollector start | stop | status to stop or check the Collector without caring about its pid.

For normal operations, you should use the <DT_HOME>/init.d/dynaTraceCollector script that starts the Collector on the desired run levels at boot time. For Linux, you can use the script without changes: Copy it to /etc/init.d and add it to boot time with chkconfig --add dynaTraceCollector.

To detect any running AppMon Collector instance, the init script checks for a file dtcollector.pid located in /var/run.

If an instance name is being used, the corresponding .pid file is called: /var/run/dtcollector.<instance>.pid. If the .pid file is not present for some reason, such as missing write permissions to /var/run, the script tries to find the process ID by grepping the ps output for running dtcollector instances. You may need to change ps and grep arguments to get the right Collector instance, which might be tricky when an instance name is being used. Therefore, it is strongly recommended to configure the system so that .pid files can be used.

dTCollector arguments

dtcollector -? renders the supported arguments:

dynaTrace Collector
Version: ... - built ...
Copyright (C) 2004-20.., dynaTrace software GmbH

Usage: dtcollector [options]

Available options:
   -?, -h, --help Print this help message
   -v             Display version information
   -loglevel [0..8]
                  Set loglevel, valid values are: [0..8] or
                  [finest|finer|fine|config|info|warning|severe|debug|none]
                  Default setting: 4 (info)
   -basedir <dir> Set working directory for application
   -ini <config>  ini file to use, default is dtcollector.ini
                  A value of 'ignore' skips reading the .ini file.
   -instance <name>
                  Instance name for this Collector instance
   -listen [<ip>:]<port>
                  Listen for dynaTrace Agents on [<ip>:]<port>
   -server <host>[:<port>]
                  Connect to dynaTrace Server at <host>[:<port>]
   -service [install | uninstall | start | stop | list(all)]
                  Install/uninstall Windows Service
                  (uninstall might require you to log off)
   -timeout <sec> Timeout value for watchdog feature, 0 turns the watchdog off.
                  Default value: 180, valid value range [30..86400] sec
   -portrange <n>[:<m>]
                  Port range to be used by watchdog feature
                  By default a port within range 50000:65535 is used
   -vm <javaVM>   The Java VM to be used for launching the application
   -startup <startup.jar>
                  The startup jar to execute. The default is to find the
                  plugins/org.eclipse.equinox.launcher jar with the highest
                  version number.
   -ea[:<package>"..."|:<class>]
                  Enable assertions (assertions are disabled by default).
                  A <package> or <class> name can be specified (cf. Java docs)
   -osgicleanonrestart
                  Clean OSGI cache on restart (set system property
                  osgi.clean=true if application gets restarted)
   -Dosgi.\*=<value>
                  Set arbitrary OSGI configuration parameters
   -D\*=<value>    Set properties for Java application
   -X\*=<value>    Set (nonstandard) options for Java VM

Automatic installation

You can automate the installation with Ansible, Chef, or Puppet. Click the link below for more detailed information.

Troubleshooting

Collector load

One particular scenario might overload the Collector: If you collectively restart your IIS instances, you should not have more than 50 Web Server Agents (depending on configuration) connected to one Collector. With normal operations, you may be able to connect more Web Server Agents to the same Collector.

Slow application startup

If you experience high application startup time, chances are that the network latency between the Agents and the Collector they connect to is too high and the number of round-trips add up. Move the Collector closer to its Agents, avoiding firewalls in between if possible, or at least use a very fast one.

Collector class cache and inheritance map sizes

Do not underestimate the impact of Collector class cache and inheritance map sizes. Despite recurrent automatic cleanup (by default every week), they can get quite big quickly. You can set cleanup recurrence with (maximum age in milliseconds; below: one day):

-Dcom.dynatrace.diagnostics.imap.cleanupItemAge=86400000

For details see KB-484 - How to fix a class cache explosion.