Configure an ActiveGate for memory dump storage

When your application experiences memory leaks or high object churn, it’s important that you get memory dumps so you can analyze these issues. In production environments, this is often a challenge when you can’t log into the environment and you have no other means of triggering memory dumps. Dynatrace enables you to both trigger and securely download memory dumps to your analysis tool of choice. To enable memory dumps, you need to configure an ActiveGate as described below.

Configuration steps

If you don’t already have an ActiveGate set up, you need to install an ActiveGate.

ActiveGate upgrade

Upon each upgrade, config.properties is updated and the existing settings are overwritten (with some exceptions—see below). To avoid losing your settings with each update, use custom.properties to preserve them. Whenever you need to configure an ActiveGate setting (for example, proxy, port, or memory dump), do this in the custom.properties file and then restart the ActiveGate.

The custom.properties file is preserved during ActiveGate upgrade (copied from your existing installation to the new one).

Edit the custom.properties file of your ActiveGate.

This file is located in the config directory of your ActiveGate installation:

  • Linux systems:
    /var/lib/dynatrace/gateway/config
  • Windows systems:
    %PROGRAMDATA%\dynatrace\gateway\config

Note: On Windows, the programdata directory is usually hidden by default. Paste the file path above into Windows Explorer to access the file.

In the [collector] section, uncomment the DumpSupported line and set the property to true.

DumpSupported = true

optional
By default, ActiveGate saves memory dumps in %PROGRAMDATA%\dynatrace\gateway\dump on Windows and /var/lib/dynatrace/gateway/dump on Linux. These directories are created by the ActiveGate installer and have appropriate permissions set. To change the default directory, edit the [dump] section and uncomment the dumpDir line.

dumpDir = dump

The dumpDir property can point to a relative path such as dumpDir = mydir. The directory will be created as a subdirectory of the default location. It can also point to an absolute path such as dumpDir = C:\data\memory-dumps.

Make sure that a user and group running the ActiveGate, dtuserag user and dtuserag group by default, have the following permissions to a custom location defined by the dumpDir property:

In the [dump] section, uncomment the following properties:

  • maxSizeGb
maxSizeGb = 100
  • maxAgeDays
maxAgeDays = 7
  • maxConcurrentUploads
maxConcurrentUploads = 5

Restart the ActiveGate.

All instances of OneAgent will automatically reconnect and recognize that the ActiveGate can now store memory dumps. Now, whenever a memory dump is successfully triggered, the dump will be uploaded automatically to the correct ActiveGate. Once safely stored on the ActiveGate, the OneAgent deletes the local file from its storage.

Limitations

  • This feature requires OneAgent version 1.127 or higher and ActiveGate version 1.127 or higher.
  • Memory dumps for IBM Java require OneAgent version 1.135 or higher.
  • Memory dump download for "PaaS application only integration" requires OneAgent version 1.139 or higher.
  • Your application server must have adequate space to store the heap dump.