OneAgent configuration via command-line interface
OneAgent version 1.179
Use the oneagentctl
command-line interface to perform some post-installation OneAgent configuration at the individual host level.
You'll find the oneagentctl tool in:
- Linux or AIX:
/opt/dynatrace/oneagent/agent/tools
You need root privileges. - Docker-based deployment
/opt/dynatrace/oneagent/agent/tools/
Note that this path will differ for a volume-based deployment. - Windows:
%PROGRAMFILES%\dynatrace\oneagent\agent\tools
You need administrator privileges. If you try to runoneagentctl
in a non-admin Windows console, Windows will display a User Account Control pop-up and fail.
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
OneAgent version 1.189
When you use the set
parameters, you need to restart OneAgent service to apply changes. Since version 1.189, 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.
For example:
- Linux or AIX:
./oneagentctl --set-proxy=my-proxy.com --restart-service
- Windows:
.\oneagentctl.exe --set-proxy=my-proxy.com --restart-service
You can also use it on its own, without other parameters.
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
Show environment ID
OneAgent version 1.185
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
OneAgent version 1.185
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
OneAgent version 1.185
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 version 1.185
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
OneAgent version 1.185
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
Log monitoring
Check if Log Monitoring is enabled
OneAgent version 1.185
Log Monitoring is not supported on AIX.
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
OneAgent version 1.185
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.
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. Most often such issues are related to deep monitoring or auto-update installations.
Check if access to system logs is enabled
OneAgent version 1.185
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
OneAgent version 1.185
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.
Note:
Disabling system log access limits our ability to diagnose and solve issues proactively. With access to system logs revoked, you may need to manually provide Dynatrace with the contents of your system logs to help us diagnose issues within your environment.
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
OneAgent version 1.193
This feature is currently supported only for Citrix Virtual Apps and Desktops and can only be used as a parameter passed during OneAgent installation.
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 automaticallyip-addresses
generate host ID based on the host IP addressip-addresses;namespace=<namespace>
if you monitor multiple environments, you can split the hosts with identical IPs using a different namespace for each environment. The namespace can contain only alphanumeric characters, hyphens, underscores, and periods; the maximum length is 256 characters.
For example, to set the host ID source to ip-addresses
and assign it to a namespace called test
, run the OneAgent installer with the following parameter:
- Linux or AIX:
./Dynatrace-OneAgent-Linux.sh --set-host-id-source="ip-addresses;namespace=test"
- Windows:
.\Dynatrace-OneAgent-Windows.exe --set-host-id-source="ip-addresses;namespace=test"
or
add--set-host-id-source="ip-addresses;namespace=test"
on the Configure OneAgent settings installer screen.
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
OneAgent version 1.179
You can use the oneagentctl
command-line interface to perform the following configuration actions for 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
Host group string requirements:
- Can contain only alphanumeric characters, hyphens, underscores, and periods
- Must not start with
dt.
- Maximum length is 100 characters
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
OneAgent version 1.189
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
OneAgent version 1.189
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 #
.
For versions earlier than 1.189, use a host metadata configuration file.
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
OneAgent version 1.187
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
OneAgent version 1.187
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.
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
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.
- 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.
To pass through the configuration parameters, simply add the parameter and precede the value with the equals sign (=
). For example:
/bin/sh Dynatrace-OneAgent-Linux.sh –-set-host-group=test_group
EXE installer
To pass the configuration parameters through using the EXE installer, simply add the parameter and precede the value with the equals sign (=
). For example:
Dynatrace-OneAgent-Windows.exe --set-host-group=test_group
MSI package
You can also pass the configuration parameters through using the MSI package. This time however, you must use an extra ADDITIONAL_CONFIGURATION
parameter. For example:
Dynatrace-OneAgent-Windows.msi ADDITIONAL_CONFIGURATION="--set-host-group=test_group"