Configuration properties and parameters of ActiveGate

Before you begin

Understand the basic ActiveGate configuration concepts related to the property files.

Basic rules for working with ActiveGate configuration

• ActiveGate configuration files

  Many ActiveGate configuration settings (for example, connectivity and proxy settings, ciphers, or memory dump settings), are stored in the config.properties and custom.properties properties files, which are located in the ActiveGate configuration directory. The properties listed in the property files are applicable for both Environment ActiveGates and Cluster ActiveGates.

  • Configuration sections

    The config.properties and custom.properties files are divided into sections. Each section name is enclosed in square brackets, for example:

    inicopydownload
    [collector]
    MSGrouter = true
    restInterface = true
    DumpSupported = false

• Do not modify settings in config.properties

  The config.properties configuration file contains the default settings with which your ActiveGate is installed. This configuration file is overwritten during each update of ActiveGate. Thus, any customized settings stored in this file will be lost (with some exceptions).

• Specify customized settings in custom.properties

  Settings stored in custom.properties take precedence over corresponding settings in config.properties, and the file is copied to the newly installed version of ActiveGate during update.

  The configuration files are divided into [sections], which are denoted by square brackets.
  To specify customized settings in custom.properties, enter section names and include the appropriate properties within these sections.

  You can use the config.txt file as a reference when you add your custom settings to the custom.properties file. The config.txt file, which is also located in the ActiveGate configuration directory, is not used by ActiveGate, however it contains a reference list of possible configuration properties. Alternatively, you can first locate the relevant section in the config.properties file and then copy the section title along with the names of the desired properties into custom.properties.
  After that, you can modify the entries in the section, as appropriate.

• ActiveGate launcher configuration file

  ActiveGate launcher is a watchdog process that starts a Java virtual machine for your ActiveGate. The launcher configuration is stored in the launcheruserconfig.conf file, in the ActiveGate configuration directory. It contains launcher properties and parameters that are passed to the Java virtual machine.
  The launcheruserconfig.conf file is preserved during ActiveGate updates.

• Restart required

  If you modify your ActiveGate configuration, you must restart the ActiveGate main service to put your changes into effect.

ActiveGate memory limits

Memory usage limits for ActiveGate can be specified in the launcher configuration file launcheruserconfig.conf.

• Memory limit settings can be a combination of:
  • -java.xmx.relative_part—percentage of available RAM, and
  • -java.xmx.absolute_part—absolute value of memory size, in MB

For example:

plaintextcopydownload
# Xmx settings 83% of available RAM + 0 MB
-java.xmx.absolute_part=0
-java.xmx.relative_part=83
-healthcheck.heartbeat.portrange=60100:60200
-arguments_section.jvm
-Dsomecustomproperty=value

ActiveGate heartbeat port range

The ActiveGate launcher monitors the ActiveGate process on a local heartbeat port. This port is chosen by the launcher, from a pre-defined range of ports, as specified in the launcher configuration. The launcher finds a free port, in the given range, and then passes the port number to the ActiveGate process.

By default, the launcher will utilize ports above 50000 for heartbeat monitoring. Certain deployments may require you to configure different ports for this purpose. To specify the port range that the ActiveGate launcher should use, add or modify the property -healthcheck.heartbeat.portrange, in the launcher configuration file launcheruserconfig.conf, as in the example below.

plaintextcopydownload
# Xmx settings 80% of available RAM + 0 MB
-java.xmx.absolute_part=0
-java.xmx.relative_part=83
-healthcheck.heartbeat.portrange=60100:60200
-arguments_section.jvm
-Dsomecustomproperty=value

Custom parameters for the ActiveGate Java process

To pass custom parameters to the ActiveGate Java process, specify the parameters in the launcher configuration file launcheruserconfig.conf:

• All lines after -arguments_section.jvm are passed as arguments to the JVM. This way, by supplying -D options, you can specify arguments for the ActiveGate.

For example:

plaintextcopydownload
# Xmx settings 80% of available RAM + 0 MB
-java.xmx.absolute_part=0
-java.xmx.relative_part=83
-healthcheck.heartbeat.portrange=60100:60200
-arguments_section.jvm
-Dsomecustomproperty=value

ActiveGate modules

Different functional features provided by ActiveGate are referred to as modules. When you are installing ActiveGate for a specific purpose, a different set of modules is installed or enabled.

A module is active if the corresponding configuration property is listed with value true in the configuration section dedicated to the module. Note, however, that you can't enable all modules using custom.properties simply by changing the value of a property: if you installed your ActiveGate to serve as a private Synthetic location or to monitor mainframe, and you need to change your ActiveGate purpose, you have to reinstall the ActiveGate.
Active modules are listed on the Deployment status page.

Module: AWS

AWS monitoring
Section: [aws_monitoring]

Module: Azure

Microsoft Azure monitoring
Section: [azure_monitoring]

Module: Cloud Foundry

Cloud Foundry monitoring
Section: [cloudfoundry_monitoring]

This section can contain proxy settings for communication with Cloud Foundry. If this section contains proxy-off = true, then there is no proxy for communication with Cloud Foundry. If it contains the proxy-host property, then this is the proxy to be used for Cloud Foundry monitoring, rather than the proxy specified in [http.client.external].
Note: If you have a [cloudfoundry_monitoring] section in your custom.properties file, you also need to have an [http.client.external] section, where you should specify all the remaining communication parameters that are to be used for Cloud Foundry communication.

Set up proxy only for Cloud Foundry monitoring

Module: Kubernetes

Kubernetes monitoring
Section: [kubernetes_monitoring]

This section can contain proxy settings for communication with Kubernetes, along with other settings related to fine-tuning communication settings for Kubernetes monitoring.
If this section contains proxy-off = true, then there is no proxy for communication with Kubernetes. If it contains the proxy-host property, then this is the proxy to be used for Kubernetes monitoring, rather than the proxy specified in [http.client.external].
Note: If you have a [kubernetes_monitoring] section in your custom.properties file, then you also need to have an [http.client.external] section, where you should specify all of the remaining communication parameters to be used for Kubernetes communication.

Set up proxy only for Kubernetes monitoring

Module: Log Monitoring

Section: [log_analytics_collector]

Section: [generic_ingest]

Specifically for Log Monitoring, when configuring Generic Log Ingest, you can customize the log data queue properties. You can specify the temporary folder where the queued log data will be stored (default is the temporary folder currently configured on your system) and, change the maximum size of the queue that will be used in that folder (default size is 300 MB).

Module: VMware

VMware monitoring
Section: [vmware_monitoring]

Module: Database insights

Oracle database insights
Section: [dbAgent]

Module: Extensions 1.0

Section: [rpm]

Module: Extensions 2.0

Section: [extension_controller]

Module: zRemote

Install the zRemote module for z/OS monitoring
Section: [zremote]

Module: Synthetic

Synthetic monitors from private Synthetic locations
Section: [synthetic]

Proxy settings for Synthetic Monitoring. If this section contains proxy-off = true, then there is no proxy for Synthetic Monitoring. If it contains the proxy-host property, then this is the proxy to be used for Synthetic Monitoring, rather than the proxy specified in [http.client.external] (or in [http.client], if [http.client.external] is not defined).
Note: If you have a [synthetic] section in your custom.properties file, you can have an [http.client.external] section, where you should specify all of the remaining communication parameters to be used for Synthetic Monitoring. Alternatively, you can specify the remaining communication settings in the [http.client] section.
However, if you do create the [http.client.external] section, you have to specify all of the communication parameters there. Otherwise, the communication parameters for monitored environments (Cloud Foundry, Kubernetes, or Synthetic Monitoring) will revert to their factory defaults.

To learn more about the proxy-related properties for a Synthetic-enabled ActiveGate, see Set up a proxy for private synthetic monitoring.

Note that changing the synthetic_enabled property only works if you installed the ActiveGate to run Synthetic monitors from a private location. If you installed the ActiveGate to route traffic, monitor cloud environments, or monitor remote technologies with extensions or monitor mainframe, you have to reinstall the ActiveGate to use it for Synthetic Monitoring. For more information, see Create a private Synthetic location.

Module: Beacon forwarder

Using ActiveGate for Real User Monitoring
Section: [beacon_forwarder]

Module: HTTP Metric API

Metric ingestion: a simple way to push any custom metrics to Dynatrace
Section: [metrics_ingest]

Module: Memory dumps

Triggering and downloading of memory dumps
Section: [collector]

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 the analysis tool of your choice.
See Configure ActiveGate for memory dump storage.

Module: OneAgent routing

ActiveGate knows about the runtime structure of your Dynatrace environment and routes messages from OneAgents to the correct server endpoints. It handles message routing, buffering, compression, authentication and accessing of sealed networks.
Section: [collector]

Module: OTLP Ingest

This module creates an endpoint on the ActiveGate that can receive OpenTelemetry trace data (traces and spans) in OTLP format. Section: [otlp_ingest]

Module: REST API

Section: [collector]
You can use an ActiveGate to access the Dynatrace API. ActiveGate supports calls to all the Dynatrace API configuration and environment endpoints in both, v1 and v2 versions. To access the Dynatrace API using ActiveGate, use a URL in the following format: https://{your-ActiveGate-domain}/e/{your-environment-id}/api/...

Load balancer address

Section: [connectivity]

Network zone

Section: [connectivity]

Group

Section: [collector]

ActiveGate file cache

The ActiveGate file cache reduces traffic between the ActiveGate and the Dynatrace Cluster by allowing OneAgents to download automatic updates from the ActiveGate rather than the Cluster.

The file cache is activated automatically when ActiveGate is installed or updated. However, activation occurs only when the minimum space requirement of 512 MB is met. If the minimum space requirement is not met, caching is automatically deactivated.

The file cache can be fine-tuned or deactivated in ActiveGate configuration, in the custom.properties file:

Section: [generic_filecache]

Section: [com.compuware.apm.webserver]

Operating over HTTPS vs HTTP

By default, ActiveGate operates in a secure way, by servicing incoming requests using HTTPS. This is specified by the port-ssl configuration property, which can be customized in the custom.properties file. However, if you want ActiveGate to use HTTP, you must specify the port property in the custom.properties.

Note that the secure way is the default and recommended one. However, you might want to choose the HTTP option for performance reasons. For example, if you have a load balancer installed in front of a Cluster ActiveGate and if the load balancer terminates incoming external SSL connections (see the third deployment scenario).

Section: [http.client]

Communication settings used for AWS/VMware/Azure monitoring and for communicating with the Dynatrace Cluster (unless overridden in [http.client.internal]). In particular, this section contains configuration properties related to proxy settings and connection timeouts.

Specify common proxy settings for Dynatrace Cluster communication and AWS/VMware/Azure monitoring.

Section: [http.client.internal]

ActiveGate version 1.207+ Settings specific to communication with the Dynatrace Cluster only.
In particular, this section can contain configuration properties related to proxy settings and connection timeouts.

If this section does not exist, communication with the Dynatrace Cluster is defined by the settings in the [http.client] section. However, if the [http.client.internal] section does exist in which a particular communication setting is not listed, then, for the purpose of communicating with the Dynatrace Cluster, the value of that setting is assumed to be its factory default (it is not inherited from [http.client]).

Set up proxy only for Dynatrace Cluster communication

Section: [http.client.external]

ActiveGate version 1.207+ Communication settings for specific modules: Cloud Foundry, Kubernetes, and also for Synthetic Monitoring.
In particular, this section can contain configuration properties related to proxy settings and connection timeouts.

If this section contains proxy-off = true, then there is no proxy for the modules. If it contains the proxy-host property, then this is the proxy to be used for the modules.

Note: Communication settings specified in [http.client] are not always used as defaults for the modules: If a particular communication setting is not specified in [http.client.external], then that setting—for Cloud Foundry, Kubernetes or Synthetic Monitoring—will revert to its factory default value, rather than to the value specified in [http.client].
Similarly, if the entire [http.client.external] section does not exist, then all of the communication settings for Kubernetes and Cloud Foundry will revert to their factory default values; however, settings for Synthetic Monitoring will assume values as specified in the [http.client] section.

Specify common proxy settings for Cloud Foundry, Kubernetes, and Synthetic Monitoring