Header background

Easily change OneAgent metadata, host name, and monitoring mode

If you have thousands of hosts to monitor, changing the configuration of some of the hosts can be challenging. With the Dynatrace OneAgent command-line interface (CLI), you can easily reconfigure your hosts or host groups anytime after installation. During the past several months, we’ve gradually improved the OneAgent CLI. You can read about these improvements in these recent blog posts:

Typically, in the case of large environments, it’s recommended that you further partition your operational set of OneAgents. You can achieve this by setting tags and properties for each OneAgent. This can be extremely helpful for search purposes and when applying configurations via the Dynatrace web UI or the recently updated Host REST API.

Equally important is the ability to change the host name or the monitoring mode within which a OneAgent operates. With the release of OneAgent 1.189, we’re happy to announce a significant improvement of the oneagentctl CLI tool which not only makes such settings possible, it also makes it easier to use these settings effectively during and after installation.

Easily add and remove tags and properties

Tags and other OneAgent metadata are convenient mechanisms for partitioning your environment for reporting, management zones, or configuration purposes. Dynatrace tagging and metadata functionality is already well established and documented. To date, however, you could only set up such tags and metadata by manually editing OneAgent configuration files.

With OneAgent 1.189, you can now perform these operations using the oneagentctl CLI tool.

  • --set-host-tag as well as --set-host-property allow for setting of tags and properties (metadata). The tags accept either labels or key-value pairs.
  • --get-host-tags and --get-host-properties allow for reading of defined tags and metadata.
  • The --remove-host-tag and --remove-host-property methods allow for the removal of tags and metadata.

Using the methods listed above, oneagentctl guarantees proper syntax, checks against duplicates, and, most importantly, makes it possible to perform operations without error-prone manual editing of configuration files.

These methods allow only for editing the metadata added using oneagentctl 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. In other words, please consider oneagentctl just a wrapper around the tag and metadata configuration files.

Note: We recommend that all customers who have created scripted solutions for managing OneAgent tags and metadata now configure their scripts to use oneagentctl as soon as possible.

Control of host name and monitoring mode

Setting up alternative (custom) host names is another well-documented option you can use to better understand and monitor the entities in your environment. With the release of OneAgent 1.189, we’re introducing a better, faster, and more resilient method for doing this. oneagentctl is now equipped with these two additional parameters:

  • --set-host-name for setting a new custom name
  • --get-host-name for reading the configured host name

The monitoring mode of OneAgent can be set up during installation, and also, conveniently, via a REST API call or Host settings in the Dynatrace web UI. However, it may be simpler and faster in some cases to configure a particular host using the command line. To enable this approach, we’ve added the following commands:

  • --set-infra-only for toggling OneAgent back and forth between Infrastructure-only mode and Full-stack mode
  • --get-infra-only retrieves the list of hosts that are set to Infrastructure-only mode

Perform streamlined configuration execution

With the introduction of these new methods, oneagentctl is now a really powerful solution. With this in mind, we’ve streamlined the execution process:

  • oneagentctl is now invoked during the installation process, which means that you can pass through the oneagentctl parameters (--set-, etc.) to the OneAgent installer for all OSes and architectures for which Dynatrace provides a full-stack solution.
  • With OneAgent 1.189, we’ve also added a --restart-service parameter so that you can perform full reconfiguration with just a single command line invocation—you can combine multiple changes and request the restart of OneAgent so that the changes go into effect.


Here’s a preview of the UI-based installer of OneAgent for Windows, where we specifically expose the oneagentctl command line window. This feature will be in production starting with OneAgent version 1.191.

UI-based installer for OneAgent for Windows

What’s next

The 1.189 version of oneagentctl and related operations described in this article concludes the current scope of investments into the CLI tool for OneAgent. We’ll keep a close eye on the feedback we receive and any new requirements. However, for the time being, our main focus will be on enhancing the REST API so that it allows for bulk post-install reconfiguration operations.


As always, we welcome your feedback and comments. Please share your thoughts with us via Dynatrace Community, or from within the Dynatrace web UI—just start a chat with a Dynatrace ONE representative. We’d love to hear from you.