Manage thousands of hosts with the new OneAgent on a host REST API (Preview)

Dynatrace helps you monitor hyper-complex environments where tribal knowledge about entities and their relationships isn’t sufficient. To achieve this, Dynatrace provides important components such as OneAgent and ActiveGate. Although we strive for full automation during rollout and maintenance, customers with complex environments often request precise configurations that can work at scale.

Dynatrace OneAgent life-cycle management allows you to control your OneAgent instance operations and core settings and answers questions like:

  • What are the statuses of my Dynatrace OneAgents?
  • Are my OneAgents and ActiveGates performing well?
  • Do I have all the latest versions installed?

So you can easily manage your OneAgents at scale, we’ve introduced support for OneAgent life-cycle management via the REST API. This is in addition to the UI and CLI (command-line interface) tools we already provide.

Simplify OneAgent life-cycle management with the new REST API

The OneAgent on a host REST API is a large project with many stages. It will allow you to:

  • Automate software management using your CMDB and scripting solution of choice.
  • Increase control over deployment via Dynatrace APIs.
  • Answer questions about your OneAgents and easily turn the answers into actions.

To address topics dealing with OneAgent management at scale, as of OneAgent version 1.185 and Dynatrace version 1.186, we’ve released the new OneAgent on a host REST API. The API methods delivered in this release will also lead to a much-improved UI that’s focused on core actions and usage flows.

How to access the OneAgent on a host REST API

All the new and updated REST API methods are available in the REST API Explorer, which you can easily access from Dynatrace. The API Explorer allows you to interactively explore and use the Dynatrace REST API right from your web browser.

In this release, we provide numerous read, search, and update methods.

From the User menu at the top right, select Environment API. Scroll down and expand the OneAgent on a host endpoint.

Additional methods are also available in the Configuration API—select the User menu > Configuration API to open the API Explorer. Expand the OneAgent on a host endpoints to view and try out the available methods.

Alternatively, you can read about all the REST API methods by accessing our online help:

Read and update OneAgent status and configuration

With the OneAgent on a host Environment API endpoint, you can read various aspects of OneAgents status and configuration.

  • Check OneAgent availability status (check the availabilityState field).
  • Check OneAgent monitoring mode (full-stack or infrastructure-only).
  • Check the auto-update setting of your OneAgent instances.
  • Check the versions of your OneAgent instances.
  • Check whether the specific OneAgent version was labeled as “faulty.” In such cases, you can also take corrective actions (upgrade to a fixed version preferably, or disable if needed).
  • Check which monitoring modules are running. You can list the existing deep-code monitoring modules this way, but the same functionality also pertains to other OneAgent modules.
  • Check the version of the monitoring module being used.
  • Check the versions of the monitoring modules labeled as faulty.
  • Check all the names and versions of the OneAgent extensions (plugins).
  • Check the operational state of OneAgents extensions (plugins).
  • Check all the possible OneAgent versions that are deployable to a particular OneAgent.

Search for OneAgents by their operational and configuration status

The following query parameters of the request allow you to search for OneAgent instances by various aspects of status and configuration.

  • Search by monitoring status (OneAgent enabled or disabled—availabilityState).
  • Search by OneAgent operation mode (full-stack or infrastructure-only—MonitoringType).
  • Search by version number (the version number can be equal to, greater, or smaller than a given reference numer—agentVersionIs in conjunction with agentVersionNumber).
  • Search for OneAgent instances labeled as “faulty” (faultyVersion).
  • Search for OneAgent instances where a specific monitoring module is present and active (technologyModuleType).
  • Search for OneAgent instances with a module of a specific version (or greater or smaller than—technologyModuleType in conjunction with technologyModuleVersionIs and technologyModuleVersionNumber).
  • Search for OneAgent instances where a specific module was labeled as “faulty” (technologyModuleType in conjunction with technologyModuleFaultyVersion).
  • Search for OneAgent instances where a specific extension, or plugin (specified by name), is deployed (pluginName).
  • Search for OneAgents with an extension (plugin) of a specific version (or greater or smaller than—pluginName in conjunction with pluginVersionIs and pluginVersionNumber).
  • Search for OneAgent instances where the extension (plugin) is in a specific operational state (pluginName in conjunction with pluginState).
  • Search for OneAgent instances with specific auto-update settings (autoUpdateSetting).

Other read and search options

The Dynatrace API comes with many other ways of reading the properties and settings of OneAgents and searching for them. In order to get the best out of what we offer, it’s important to explore the API via the API Explorer and to adjust the search results and techniques to your particular needs.

Specifically, here are some of the most useful read and search attributes that can be found in the ../api/v1/oneagents family:

  • tag—Filters the resulting set of hosts by the specified tag. You can specify several tags in the following format: tag=tag1&tag=tag2. The host must match all the specified tags, and in case of key-value tags such as imported AWS or CloudFoundry tags, use following format: [context]key:value.
  • managementZoneId (ID) or its alternative managementZone (name)—Only returns hosts that are part of the specified management zone.
  • hostGroupId and hostGroupName—Filters the resulting set of hosts by the specified host group by ID or name.
  • osType—Filters the resulting set of hosts by their OS type: AIX, DARWIN, HPUX, LINUX, SOLARIS, WINDOWS, ZOS.

Note: To check the host units effectively consumed by the OneAgent deployed on a particular host you can use this previously released REST API endpoint:

../api/v1/entity/infrastructure/hosts/{entity (consumedHostUnits: string)

Paginated search results

In some cases, the result of search operations can amount to multiple pages. While processing the results, take note of the “next page” identifiers and resend the search query for follow-up portions of the result set.

Update OneAgent configuration

There are several write operations available as part of the OneAgent on a host Configuration API in this release. Here’s a description of the full functionality of the endpoints.

With the Configuration API endpoint for OneAgent auto-update you can:

  • Check the OneAgent auto-update setting.
  • Update the OneAgent auto-update setting.

With the Configuration API endpoint for OneAgent monitoring configuration you can:

  • Check if OneAgent is enabled or disabled on a particular host.
  • Enable or disable OneAgent on a particular host.
  • Check OneAgent monitoring mode (full-stack or infrastructure-only).
  • Change the OneAgent monitoring mode.

With the Configuration API endpoint for OneAgent technology monitoring configuration you can:

  • Check how monitoring modules are configured (to validate whether the configuration actually matches the operational status).

Important

  • This is only the first noteworthy release of this project—much, much more is coming.
  • This release focuses on the REST API, but we’re also going to implement UI changes to assure full parity.
  • Next, we’ll focus more on write operations and make it possible to increasingly control deployment via Dynatrace APIs.

In addition to the REST API, also note that we’re continuously pushing our changes to the OneAgent CLI (command-line interface). You can read more about the current release in this blog post.

How to participate in the Preview

Note that this is a Preview and is available by subscription only.

To participate in the Preview, scroll down to the In Progress section, expand the entry for OneAgent life-cycle management via REST API and select Join the Preview. Once you’ve filled in and submitted the required details, you’ll be contacted by Dynatrace.

Note: Please be aware that not all who register for the Preview will make it to the final list; we may run out of Preview slots.

Feedback?

As always, we welcome your feedback and comments. Please share your thoughts via Dynatrace Answers, directly within the product through Dynatrace ONE chat, or your Dynatrace Account Manager.

Stay updated