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 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

Dynatrace stores ActiveGate configuration settings in the file config.properties.
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

In the [dump] section, uncomment the dumpDir line.

dumpDir = dump

The directory provided in the dumpDir property setting will be created in the same directory where the dynatracegateway is run. For example, with the dumpDir = dump configuration and the dynatracegateway run in /opt/dynatrace/gateway/launcher/ directory, the dump will be created in:
/opt/dynatrace/gateway/launcher/dump/.

If you create the dump directory manually and specify the full path to that dump directory, make sure that you set the read/write permissions to that directory for a user who runs the ActiveGate.

  • Linux systems:
    The user must have the Read, Write, and Execute permissions on the directory.

  • Windows systems:
    This requires that the user who runs the ActiveGate service has the Read, Write, and Modify permissions.

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.