OneAgent configuration via command-line interface

Use the oneagentctl command-line interface to perform some post-installation OneAgent configuration at the individual host level.

Location

The tool location depends on whether you customized the OneAgent installation using the <INSTALL_PATH> parameter:

• Linux or AIX:
  <INSTALL_PATH>/agent/tools, by default /opt/dynatrace/oneagent/agent/tools
  You need root privileges.
• Docker-based deployment
  <INSTALL_PATH>/agent/tools, by default /opt/dynatrace/oneagent/agent/tools
  Note that this path will differ for a volume-based deployment.
• Windows:
  <INSTALL_PATH>\agent\tools, by default %PROGRAMFILES%\dynatrace\oneagent\agent\tools
  You need administrator privileges. If you try to run oneagentctl in a non-admin Windows console, Windows will display a User Account Control pop-up and fail.

Parameter types

oneagentctl command-line interface provides you with get parameters to check the state or value of a setting, and set parameters to change a setting. Note that you can use a number of set parameters in a single command.

OneAgent restart

When you use the set parameters, you need to restart OneAgent service to apply changes. You can use the --restart-service parameter with the command that triggers the restart automatically. In some cases you'll also need to restart monitored applications. You can also use the restart parameter on its own, without other parameters. See an example command below.

• Linux or AIX:
  ./oneagentctl --set-proxy=my-proxy.com --restart-service
• Windows:
  .\oneagentctl.exe --set-proxy=my-proxy.com --restart-service

Display help

Use the --help parameter to display all supported parameters.

• Linux or AIX:
  ./oneagentctl --help
• Windows:
  .\oneagentctl.exe --help

Display OneAgent version

Use the --version parameter to display the OneAgent version.

• Linux or AIX:
  ./oneagentctl --version
• Windows:
  .\oneagentctl.exe --version

OneAgent communication

Change OneAgent communication settings

OneAgent version 1.185

• Use the --set-server parameter to set a OneAgent communication endpoint. Use the IP address or name. Depending on your deployment, it can be a Dynatrace Server, Dynatrace Managed Cluster, or ActiveGate.
• Use the --set-tenant parameter to set an environment ID. By default, this is already set to the correct value. If you're selling Dynatrace-based services, use this option to set your customers' IDs from the pool of IDs you purchased from Dynatrace. Always use in combination with --set-tenant-token, which defines the tenant token for internal authentication.
• Use the --set-tenant-token parameter to set the tenant token, which is used to authenticate communication with the defined endpoint. Always use in combination with --set-tenant
• Use the --set-proxy parameter to set a proxy server.

Run the following command to adjust OneAgent connection settings:

• Linux or AIX:
  ./oneagentctl --set-server=https://my-server.com:443 --set-tenant=abc123456 --set-tenant-token=abcdefg123456790 --set-proxy=my-proxy.com
• Windows:
  .\oneagentctl.exe --set-server=https://my-server.com:443 --set-tenant=abc123456 --set-tenant-token=abcdefg123456790 --set-proxy=my-proxy.com

These parameters require restart of OneAgent, as well as restart of all the applications monitored with deep code modules. Add –restart-service to the command to restart OneAgent automatically (version 1.189+) or stop and start OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

This command will immediately change the OS module connection endpoint, but the code modules won't be able to read the new setting until the next restart.

OneAgent and Dynatrace Cluster automatically maintain a working connection. If an endpoint detail changes, the cluster notifies OneAgent of the change and OneAgent automatically updates the endpoint you set using the --set-server to the new working value.

Show current communication endpoints

OneAgent version 1.185

Use the --get-server parameter to display the endpoints that OneAgent is to send the data to. These can be Dynatrace Server, Dynatrace Managed Cluster or ActiveGate.

• Linux or AIX:
  ./oneagentctl --get-server
• Windows:
  .\oneagentctl.exe --get-server

Starting with OneAgent version 1.207, endpoints are reported using a format in which endpoints of equal priority are grouped using braces ({...}) and sorted according to connection priority. An asterisk (*) indicates the endpoint to which OneAgent currently sends the data. Endpoints are separated by a semicolon (;). For example:

{https://endpoint1.com/communication;https:/10.0.0.0/communication;*https://endpoint3.com/communication}{https://endpoint4.com:443/communication}

Show environment ID

The Dynatrace environment ID you received with your activation email.

Use the --get-tenant parameter to display the environment ID:

• Linux or AIX:
  ./oneagentctl --get-tenant
• Windows:
  .\oneagentctl.exe --get-tenant

Show tenant token

Use the --get-tenant-token parameter to display the currently defined token:

• Linux or AIX:
  ./oneagentctl --get-tenant-token
• Windows:
  .\oneagentctl.exe --get-tenant-token

Show current proxy

OneAgent version 1.185

Use the --get-proxy parameter to display the currently defined proxy OneAgent connects through:

• Linux or AIX:
  ./oneagentctl --get-proxy
• Windows:
  .\oneagentctl.exe --get-proxy

Clear proxy configuration

Use the --set-proxy parameter set to an empty value to clear proxy configuration:

• Linux or AIX:
  ./oneagentctl --set-proxy=
• Windows:
  .\oneagentctl.exe --set-proxy=

Restart OneAgent service to apply changes.

Check current port range

OneAgent consists of different processes that communicate via a TCP port with a watchdog. At startup, OneAgent watchdog attempts to open the first available port between port 50000 and 50100. In some cases you may need this port for your own applications that are started after OneAgent.

Use the --get-watchdog-portrange parameter to check the current port range defined for the watchdog.

• Linux or AIX:
  ./oneagentctl --get-watchdog-portrange
• Windows:
  .\oneagentctl.exe --get-watchdog-portrange

Set a new port range

Use the --set-watchdog-portrange=arg parameter to change the watchdog listening port range to <arg>. The <arg> must contain two port numbers separated by a colon (:). For example 50000:50100. The maximum supported port range is from 1024 to 65535. The port range must cover at least 4 ports. The port number starting the range must be lower.

• Linux or AIX:
  ./oneagentctl --set-watchdog-portrange=50000:50100
• Windows:
  .\oneagentctl.exe --set-watchdog-portrange=50000:50100

Automatic updates

OneAgent version 1.213

For more information, see update OneAgent topics for Linux, Windows, and AIX.

Check if auto-update is enabled

Use the get-auto-update-enabled parameter to check whether OneAgent auto-update is enabled:

• Linux or AIX:
  ./oneagentctl --get-auto-update-enabled
• Windows:
  .\oneagentctl.exe --get-auto-update-enabled

Enable or disable auto-update

Set the --set-auto-update-enabled parameter to true or false to disable or enable OneAgent auto-update:

• Linux or AIX:
  ./oneagentctl --set-auto-update-enabled=true
• Windows:
  .\oneagentctl.exe --set-auto-update-enabled=true

Caution: after you use this command to disable auto-updates, you won't be able to control OneAgent automatic updates using the Dynatrace web UI at Settings > Preferences > OneAgent updates.

Log monitoring

For more information, see Log Monitoring. Note: Log Monitoring is not supported on AIX.

Check if Log Monitoring is enabled

Use the --get-app-log-content-access parameter to check whether Log Monitoring is enabled:

• Linux:
  ./oneagentctl --get-app-log-content-access
• Windows:
  .\oneagentctl.exe --get-app-log-content-access

Enable or disable Log Monitoring

Set the --set-app-log-content-access parameter to true or false to disable or enable Log Monitoring:

• Linux:
  ./oneagentctl --set-app-log-content-access=true
• Windows:
  .\oneagentctl.exe --set-app-log-content-access=true

Restart OneAgent service to apply changes.

Create support archive

OneAgent version 1.225+

If you don't have access to the Dynatrace web UI or you would like to script diagnostic data collection, you can use the oneagentctl command-line interface to collect a subset of the full OneAgent diagnostics data right on the host where OneAgent is installed. With the diagnostic data collected for OneAgent, you can:

• Easily collect the diagnostic data for a specific host
• Directly provide Dynatrace Support the details they need to diagnose the issue

The command requires the OneAgent service to be running.

To create a support archive with diagnostic data, run oneagentctl with the --create-support-archive parameter. By default, the support archive contains the data for a 7-day time frame and is created in the current working directory. Optionally, you can set a custom directory and timeframe with the directory and days parameters. Note: onegentctl won't create a directory; you must point it to an existing directory with a relative or absolute path. For example:

• Linux or AIX:
  ./oneagentctl --create-support-archive directory=/data/support-archive days=30
• Windows:
  .\oneagentctl.exe --create-support-archive directory=C:\data\support-archive days=30

The command saves the archive as the support_archive_agent_YYYY-MM-DD_hhmmss.zip file. For example:

Creating support archive from last 30 days in C:\data\support-archive
Waiting 30s for archive request to be processed
Processing archive, waiting up to 15m 0s
Archive saved as C:\data\support-archive\support_archive_agent_2021-09-07_121619.zip

Contents of diagnostic data

All the collected diagnostic data is compressed into a support_archive_agent_YYYY-MM-DD_hhmmss.zip archive that includes the following subset of the full OneAgent diagnostics data:

Access to system logs for proactive support

OneAgent downloads specific system logs so that Dynatrace can diagnose issues that may be caused by conditions in your environment. The logs are also saved in the support archive. Most often such issues are related to deep monitoring or auto-update installations.

Check if access to system logs is enabled

Use the --get-system-logs-access-enabled parameter to check whether access to system logs is enabled:

• Linux or AIX:
  ./oneagentctl --get-system-logs-access-enabled
• Windows:
  .\oneagentctl.exe --get-system-logs-access-enabled

Enable or disable access to system logs

Set the --set-system-logs-access-enabled parameter to true or false to disable or enable access to system logs:

• Linux or AIX:
  ./oneagentctl --set-system-logs-access-enabled=true
• Windows:
  .\oneagentctl.exe --set-system-logs-access-enabled=true

Restart OneAgent service to apply changes.

Note that the --set-system-logs-access-enabled and --get-system-logs-access-enabled parameters refer to a self-diagnostics setting and are not related to Log Monitoring.

Host ID

Dynatrace assigns a unique ID to each host monitored in your environment. Host IDs can be used as parameters in Dynatrace API requests, for example Topology and Smartscape API - Hosts API. The host ID also constitutes the URL of the Host overview page, for example, https://environment.org/#newhosts/hostdetails;id=HOST-6E56EE455C84E232.

Display your host ID

OneAgent version 1.197

To find a host ID, use the --get-host-id parameter. For example:

• Linux or AIX:
  ./oneagentctl --get-host-id
• Windows:
  .\oneagentctl.exe --get-host-id

Define the host ID source

Available on all supported platforms for OneAgent version 1.223+. For OneAgent version 1.221 and earlier, this feature is supported only for Citrix Virtual Apps and Desktops.

It's particularly important to keep you host ID static in dynamic virtual environments where hosts are recreated on a daily basis.

To define the source for host ID generation, use --set-host-id-source and set it to one of the predefined values:

• auto — Let Dynatrace generate the host ID automatically
• ip-addresses — Generate host ID based on the host IP address
• mac-address — Generate host ID based on the host's NIC MAC address
• fqdn — Generate host ID based on the host fully qualified domain name (FQDN) in the host.domain format. If the FQDN doesn't contain a dot character, the NIC MAC address is used instead.
• If you monitor multiple environments, you can split the hosts with identical IPs, MAC addresses, or FQDNs using a different namespace for each environment. The namespace can contain only alphanumeric characters, hyphens, underscores, and periods; the maximum length is 256 characters.
  • ip-addresses;namespace=<namespace>
  • mac-addresses;namespace=<namespace>
  • fqdn;namespace=<namespace>

For example, to set the host ID source to ip-addresses and assign it to a namespace called test, run oneagentctl with the following parameter:

• Linux or AIX:
  ./oneagentctl --set-host-id-source="ip-addresses;namespace=test"
• Windows:
  .\oneagentctl.exe --set-host-id-source="ip-addresses;namespace=test"

After you change the host ID source, you must restart all your monitored applications and then restart the OneAgent service to create the new host entity in your environment. You can use the --restart-service parameter with oneagentctl to restart OneAgent automatically or stop and start OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

To check the host ID source, use the --get-host-id-source parameter:

• Linux or AIX:
  ./oneagentctl --get-host-id-source
• Windows:
  .\oneagentctl.exe --get-host-id-source

For host ID source set to ip-addresses and the test namespace, the command will return the following result:

ip-addresses;namespace=test

Host groups

For an overview of how to use host groups, see Organize your environment using host groups.

Change host group assignment

Use the --set-host-group parameter to change the host group assignment.

To assign the host to MyHostGroup:

• Linux or AIX:
  ./oneagentctl --set-host-group=MyHostGroup
• Windows:
  .\oneagentctl.exe --set-host-group=MyHostGroup

Using --set-host-group requires restart of OneAgent, as well as restart of all the monitored services. Add –restart-service to the command to restart OneAgent automatically (version 1.189+) or stop and start OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

Clear host group assignment

Use the --set-host-group parameter with an empty value to clear the host group assignment:

• Linux or AIX:
  ./oneagentctl --set-host-group=
• Windows:
  .\oneagentctl.exe --set-host-group=

Display host group assignment

Use the --get-host-group parameter to display the current host group assignment:

• Linux or AIX:
  ./oneagentctl --get-host-group
• Windows:
  .\oneagentctl.exe --get-host-group

Host tags and metadata

Within dynamic or large environments, manual host tagging can be impractical. For dynamic deployments that include frequently changing host instances and names (for example, AWS or MS Azure), you can use dedicated oneagentctl parameters to apply custom tags, names, and metadata to your hosts.

The oneagentctl methods listed below allow only for editing the metadata added using oneagentctl itself or previously using the configuration files. Tags and metadata added using Dynatrace web UI, as well as retrieved from a monitored environment (for example the AWS tags) are not editable with oneagentctl and won't be displayed using --get-host-tags and --get-host-properties parameters.

Custom host name

Use the oneagentctl command-line tool with the --set-host-name parameter to override an automatically detected host name. A host name must not contain the <, >, &, CR (carriage return), or LF (line feed) characters. The maximum length is 256 characters.

To change the host name:

• Linux or AIX: ./oneagentctl --set-host-name=myhostname
• Windows: .\oneagentctl.exe --set-host-name=myhostname

To revert to the auto-detected host name, set the --set-host-name parameter to an empty value, as in --set-host-name="". For example:

• Linux or AIX: ./oneagentctl --set-host-name=""
• Windows: .\oneagentctl.exe --set-host-name=""

The change might not be reflected in the Dynatrace web UI for up to 6 minutes.

Using --set-host-name requires restart of OneAgent. Add --restart-service to the command to restart OneAgent automatically (version 1.189+) or stop and start the OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

To show the host name:

• Linux or AIX:
  ./oneagentctl --get-host-name
• Windows:
  .\oneagentctl.exe --get-host-name

Custom host metadata

Once configured, custom metadata is displayed as a set of properties at the bottom of the Properties and tags section of the host overview page. The property values must not contain an = character (unless used as a key-value delimiter) or whitespace characters. The maximum length is 256 characters, including the key-value delimiter. The key name must not start with a # character.

For versions earlier than 1.189, use a host metadata configuration file.

To add or change host properties, run the following command:

• Linux and AIX
  ./oneagentctl --set-host-property=AppName --set-host-property=Environment=Dev
• Windows
  .\oneagentctl.exe --set-host-property=AppName --set-host-property Environment=Dev

You can add or change more than one property in the same command.

To remove host properties, run the following command:

• Linux and AIX

./oneagentctl --remove-host-property=AppName --remove-host-property=Environment=Dev

• Windows

.\oneagentctl.exe --remove-host-property=AppName --remove-host-property=Environment=Dev

You can remove more than one property with a single command. If a property key that's passed in the command doesn't exist, a non-zero exit code will be returned, but all the existing properties passed in the command will be removed. After you remove host properties, they remain visible in the Dynatrace web UI for up to 7 hours.

To show all properties configured for the host, run the following command:

• Linux and AIX

./oneagentctl --get-host-properties

• Windows

.\oneagentctl.exe --get-host-properties

Custom host tags

After you configure custom host tags, they are displayed at the top of the Properties and tags section of the host overview page. A property value must not contain = (unless used as a key-value delimiter) or whitespace characters. The maximum length is 256 characters, including the key-value delimiter. A key name must not start with #.

To add or change host tags, run the following command:

• Linux and AIX
  ./oneagentctl --set-host-tag=TestHost --set-host-tag=role=fallback --set-host-tag=Gdansk
• Windows
  .\oneagentctl.exe --set-host-tag=TestHost --set-host-tag=role=fallback --set-host-tag=Gdansk

You can add or change more than one tag in the same command. It is allowed to define tags with the same key but different values.

To remove tags, run the following command:

• Linux and AIX

./oneagentctl --remove-host-tag=role=fallback --remove-host-tag=Gdansk

• Windows

.\oneagentctl.exe --remove-host-tag=role=fallback --remove-host-tag=Gdansk

You can remove more than one tag with the same command. If a tag passed in the command doesn't exist, a non-zero exit code is returned, but all the existing tags passed in the command are removed. After you remove tags, they remain visible in the Dynatrace web UI for up to 6 hours.

To show all tags configured for the host, run the following command:

• Linux and AIX

./oneagentctl --get-host-tags

• Windows

.\oneagentctl.exe --get-host-tags

Infrastructure Monitoring

Use the Infrastructure Monitoring mode, in place of full-stack monitoring mode. With this approach, you receive infrastructure-only health data, with no application or user performance data. For details, see Infrastructure Monitoring.

Check if Infrastructure Monitoring mode is enabled

Use the --get-infra-only parameter to check whether Infrastructure Monitoring mode is enabled:

• Linux or AIX:
  ./oneagentctl --get-infra-only
• Windows:
  .\oneagentctl.exe --get-infra-only

Enable or disable Infrastructure Monitoring mode

Set the --set-infra-only parameter to true or false to enable or disable Infrastructure Monitoring mode.

To enable Infrastructure Monitoring mode:

• Linux or AIX:
  ./oneagentctl --set-infra-only=true
• Windows:
  .\oneagentctl.exe --set-infra-only=true

Changing the Infrastructure Monitoring mode requires restart of OneAgent, as well as restart of all monitored services. Add –restart-service to the command to restart OneAgent automatically (version 1.189+) or stop and start the OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

Automatic injection in Infrastructure Monitoring

OneAgent version 1.213

Automatic OneAgent injection is enabled by default in Infrastructure Monitoring mode to get and report the JMX/PMI metrics.

For more information, see Infrastructure Monitoring mode.

Check if auto-injection is enabled

Use the get-auto-injection-enabled parameter to check whether OneAgent auto-injection is enabled:

• Linux or AIX:
  ./oneagentctl --get-auto-injection-enabled
• Windows:
  .\oneagentctl.exe --get-auto-injection-enabled

Enable or disable auto-injection

Set the --set-auto-injection-enabled parameter to true or false to disable or enable OneAgent auto-injection:

• Linux or AIX:
  ./oneagentctl --set-auto-injection-enabled=true
• Windows:
  .\oneagentctl.exe --set-auto-injection-enabled=true

We don't recommend that you disable automatic injection, but you can disable it if you have very strict security requirements.

Caution: if you use this command to disable automatic injection, you won't be able to control auto-injection in Infrastructure Monitoring mode using the Dynatrace web UI at Settings > Monitoring > Monitored technologies.

After you disable auto-injection, restart all OneAgent-injected applications.

Metric ingestion

OneAgent version 1.201

Local metric ingestion is currently supported only on Windows and Linux.

You can use the oneagentctl command line interface to check or change communication ports used for local metric ingestion using the OneAgent metric API, Scripting integration, Telegraf, or DynatraceStatsd. Changing the metric ingestion port requires restart of OneAgent. Add –restart-service to the command to restart OneAgent automatically.

See Metrics ingestion to learn more.

OneAgent API, scripting integration, and Telegraf

The default metric ingestion port is 14499. If necessary, you can use oneagentctl command-line interface to check or change the port. Changing the metric ingestion port requires restart of OneAgent. Add –restart-service to the command to restart OneAgent automatically.

Check the ingestion port

Use the --get-extensions-ingest-port parameter to show the current local ingestion port, 14499 by default.

• Linux: ./oneagentctl --get-extensions-ingest-port
• Windows: .\oneagentctl.exe --get-extensions-ingest-port

Set a custom ingestion port

Use the --set-extensions-ingest-port=<arg> parameter to set a custom local ingestion port.

• Linux: ./oneagentctl --set-extensions-ingest-port=14499 --restart-service
• Windows: .\oneagentctl.exe --set-extensions-ingest-port=14499 --restart-service

Configure proxy

Configure your host proxy to allow localhost traffic going to the metric ingestion port, 14499 by default.

StatsD

The default DynatraceStatsD UDP listening port is 18125. If necessary, you can use oneagentctl command-line interface to check or change the metric ingestion port. Changing the port requires restart of OneAgent. Add –restart-service to the command to restart OneAgent automatically.

Check the ingestion port

Use the --get-extensions-statsd-port parameter to show the current DynatraceStatsd UDP listening port (default = 18125).

• Linux: ./oneagentctl --get-extensions-statsd-port
• Windows: .\oneagentctl.exe --get-extensions-statsd-port

Set a custom ingestion port

Use the --set-extensions-statsd-port=<arg> parameter to set a custom DynatraceStatsd UDP listening port.

• Linux: ./oneagentctl --set-extensions-statsd-port=18125 –restart-service
• Windows: .\oneagentctl.exe --set-extensions-statsd-port=18125 –restart-service

Network zones

To learn about network zone naming rules and other reference information, see Network zones.

Set a network zone

Use the --set-network-zone parameter to instruct OneAgent to communicate via the specified network zone. The name of a network zone is a string of alphanumeric characters. You can also use hyphens (-), underscores (_), and a dot (.) as a seperator. The network zone name must not start with a dot. The length of the string is limited to 256 characters. Network zone names are not case-sensitive. Dynatrace stores these names in lowercase. For more information, see Network zones naming

• On Linux or AIX:
  ./oneagentctl --set-network-zone=<your.network.zone>
• On Windows:
  .\oneagentctl.exe --set-network-zone=<your.network.zone>

Reset a network zone

You can reset the network zone setting by passing an empty network zone name:

• On Linux or AIX:
  ./oneagentctl --set-network-zone=""
• On Windows:
  .\oneagentctl.exe --set-network-zone=""

Display network zone setting

Use the --get-network-zone parameter to display the current network zone configuration:

• On Linux or AIX:
  ./oneagentctl --get-network-zone
• On Windows:
  .\oneagentctl.exe --get-network-zone

Passing configuration parameters during installation

You can pass the --set-* parameters at installation time. The configuration parameters are applied right before OneAgent service starts and there's no need to restart it to apply your configuration.

/bin/sh Dynatrace-OneAgent-Linux.sh –-set-host-group=test_group

Dynatrace-OneAgent-Windows.exe --set-host-group=test_group

Dynatrace-OneAgent-Windows.msi ADDITIONAL_CONFIGURATION="--set-host-group=test_group"