Header background

Faster host-group management using the OneAgent command-line interface

Imagine a situation where you have 1,000 hosts to monitor. Regardless of how awesome the default settings are, at some stage, you’ll want to change the configuration of some of these hosts. For example, you might want Dynatrace to treat a group of hosts in a load-balancer environment as a single virtual host. This is possible via the host-group feature, but until recently, required a full OneAgent installation. With the new OneAgent command-line interface (CLI), you can change configurations at any time without a hassle.

In February 2019 we announced a Preview of the OneAgent command-line interface (CLI) solution, which allows for easier post-installation host-group reconfiguration. Today, we’re happy to announce that this solution is Generally Available as of OneAgent version 1.179.

What’s new in the GA release?

The OneAgent CLI Preview was well received, and we were able to collect some interesting feedback. Many of our customers asked for more settings to be exposed this way, and of course, we’ll do our best to satisfy these requests (read about it below).

Better naming in line with current standards

There’s a binary that now allows for controlled and validated reconfiguration of OneAgents in cases where full reinstallaton or configuration file changes were the only options previously available. Up to now, this binary was called oneagentutil.

Many of our Preview participants suggested that a slightly different name for the CLI would be better aligned with current naming standards. So we’ve decided to rename oneagentutil to oneagentctl, effective with OneAgent version 1.179. This small but important change will hopefully introduce negligible overhead for those customers who’ve started building scripting around oneagentutil.

Note: The syntax of the CLI remains unchanged, and besides the renaming of the binary file itself, is fully backwards compatible with the Preview versions.

Quickly find out which OneAgent version you have

You might have scenarios where OneAgent updates aren’t automatic and so you need to script and execute them manually on the host. To help you here, we’ve added a new parameter, --version. This parameter tells you which OneAgent version is currently installed on your system.

More security during configuration updates

In some cases in the past, the reconfiguration of certain parameters on a live OneAgent could cause erratic behavior. To make sure you have full security during configuration updates, oneagentctl now guards the stop-update-start routine in case of any serious configuration updates. This ensures that no changes can be made while OneAgent is running.

New binary location

Finally, we’ve improved the location of the oneagentctl file. The bit size of your environment no longer impacts the location of the binary, so you don’t need to know anymore if your environment is 32 bit or 64 bit.

One syntax to rule them all

Our changes reach much further than just the oneagentctl binary name. You can always invoke oneagentctl --help to learn about possible operators, but in order to make it easier to remember, we decided to make sure the same syntax is applied to oneagentctl as well as to the installer script.

And so, starting with version 1.179, the OneAgent installer also accepts the --set-host-group parameter in parallel to the existing HOST_GROUP parameter. You can read about all installation parameters in Dynatrace Help. As you’ll read about below, we also plan to add other parameters to oneagentctl. We’ll make sure that each such addition is covered by a respective counterpart in the OneAgent installer script.

Old installation parameters will be removed from the OneAgent installer script

Eventually, old installation parameters (such as HOST_GROUP) will be removed from the OneAgent installer script. Please be assured that we’ll issue a corresponding deprecation notice well before the final removal. When that happens, you’ll need to update your scripts to reflect the new naming standard (parameters starting with --set-...) as soon as it’s convenient. Stay tuned for more announcements on this topic.

For the growing list of oneagentctl parameters, please check this Dynatrace Help article or simply invoke oneagentctl --help.

What’s next in the CLI

Over the next several releases, we’ll be working hard to provide many more features to the OneAgent CLI-based reconfiguration tool. You can expect the following parameters to appear shortly:

  • Get/set network zones (This is an upcoming feature; please check for our announcement on this topic soon.)
  • Get monitoring mode (Full-stack vs. cloud infrastructure only)
  • Add/remove/list host tags and other metadata (Read full details.)
  • Get/set custom hostname (Read full details.)
  • Get/set server+tenant+token+proxy tuple or any of the components (This can be very helpful in cases where OneAgent needs to be moved between environments.)
  • Set watchdog port range (This is a very specific setting that, in most cases, shouldn’t be changed. Read full details.)

Feedback is welcome

As always, we welcome your feedback and comments. Please share them via Dynatrace Community, Dynatrace Support, or your Dynatrace Account Manager.