OneAgent on a host API

The OneAgent on a host API enables you to check the configuration of OneAgent instances on your hosts.

The request produces an application/json payload.

GETSaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/oneagents
Environment ActiveGatehttps://{your-activegate-domain}:9999/e/{your-environment-id}/api/v1/oneagents

Authentication

To execute this request, you need an access token with one of the following scopes:

  • oneAgents.read
  • DataExport

To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter
Type
Description
In
Required
includeDetails
boolean

Includes (true) or excludes (false) details which are queried from related entities.

Excluding details may make queries faster.

If not set, then true is used.

query
optional
startTimestamp
integer

The start timestamp of the requested timeframe, in milliseconds (UTC).

If not set, then 72 hours behind from now is used.

query
optional
endTimestamp
integer

The end timestamp of the requested timeframe, in milliseconds (UTC).

If not set, then the current timestamp is used.

The timeframe must not exceed 7 months (214 days).

query
optional
relativeTime
string

The relative timeframe, back from now.

If you need to specify relative timeframe that is not presented in the list of possible values, specify the startTimestamp (up to 214 days back from now) and leave endTimestamp and relativeTime empty.

  • 10mins
  • 15mins
  • 2hours
  • 30mins
  • 3days
  • 5mins
  • 6hours
  • day
  • hour
  • min
  • month
  • week
query
optional
tag
string[]

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 has to match all the specified tags.

In case of key-value tags, such as imported AWS or CloudFoundry tags, use the following format: tag=[context]key:value. For custom key-value tags, omit the context: tag=key:value.

query
optional
entity
string[]

Filters result to the specified hosts only.

To specify several hosts use the following format: entity=ID1&entity=ID2.

query
optional

Response

Response codes

Code
Type
Description
200

Success

4XX

Client side error.

5XX

Server side error.

Response body objects

The HostsListPage object

A list of hosts with OneAgent deployment information for each host.

Element
Type
Description
hosts

A list of hosts with OneAgent deployment information for each host.

nextPageKey
string

The cursor for the next page of results.

Has the value of null on the last page.

There might be another page of results even if the current page is empty.

percentageOfEnvironmentSearched
number

The progress of the environment search, in percent.

The HostAgentInfo object

OneAgent deployment on a host.

Element
Type
Description
active
boolean

OneAgent is active (true) or inactive (false).

autoUpdateSetting
string

The effective auto-update setting of OneAgent. For host with inherited configuration it is calculated from its parent's configuration

  • ENABLED
  • DISABLED
availabilityState
string

The availability state of OneAgent.

  • CRASHED
  • LOST
  • MONITORED
  • PRE_MONITORED
  • SHUTDOWN
  • UNEXPECTED_SHUTDOWN
  • UNKNOWN
  • UNMONITORED
availableVersions
string[]

A list of versions OneAgent can be updated to.

configuredMonitoringEnabled
boolean

Monitoring is enabled (true) or disabled (false) in the OneAgent configuration.

configuredMonitoringMode
string

Configured monitoring mode of OneAgent.

  • CLOUD_INFRASTRUCTURE
  • DISCOVERY
  • FULL_STACK

The Host object

Information about the host.

Element
Type
Description
agentVersion

Defines the version of the agent currently running on the entity.

amiId
string
-
autoInjection
string

Status of auto-injection

  • DISABLED_MANUALLY
  • DISABLED_ON_INSTALLATION
  • DISABLED_ON_SANITY_CHECK
  • ENABLED
  • FAILED_ON_INSTALLATION
autoScalingGroup
string
-
awsInstanceId
string
-
awsInstanceType
string
-

The AgentVersion object

Defines the version of the agent currently running on the entity.

Element
Type
Description
major
integer

The major version number.

minor
integer

The minor version number.

revision
integer

The revision number.

sourceRevision
string

A string representation of the SVN revision number.

timestamp
string

A timestamp string: format "yyyymmdd-hhmmss

The HostGroup object

Element
Type
Description
meId
string

The Dynatrace entity ID of the host group.

name
string

The name of the Dynatrace entity, displayed in the UI.

The EntityShortRepresentation object

The short representation of a Dynatrace entity.

Element
Type
Description
description
string

A short description of the Dynatrace entity.

id
string

The ID of the Dynatrace entity.

name
string

The name of the Dynatrace entity.

The TechnologyInfo object

Element
Type
Description
edition
string
-
type
string
-
version
string
-

The TagInfo object

Tag of a Dynatrace entity.

Element
Type
Description
context
string

The origin of the tag, such as AWS or Cloud Foundry.

Custom tags use the CONTEXTLESS value.

  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_CLOUD
  • KUBERNETES
key
string

The key of the tag.

Custom tags have the tag value here.

value
string

The value of the tag.

Not applicable to custom tags.

The ModuleInfo object

OneAgent code module.

Element
Type
Description
instances

A list of instances of the code module.

moduleType
string

The type of the code module.

  • APACHE
  • DOT_NET
  • DUMPPROC
  • GO
  • IBM_INTEGRATION_BUS
  • IIS
  • JAVA
  • LOG_ANALYTICS
  • NETTRACER
  • NETWORK
  • NGINX
  • NODE_JS
  • OPENTRACINGNATIVE
  • PHP
  • PROCESS
  • PYTHON
  • RUBY
  • SDK
  • UPDATER
  • VARNISH
  • Z_OS

The ModuleInstance object

An instance of the OneAgent code module.

Element
Type
Description
active
boolean

The code module instance is active (true) or inactive (false).

faultyVersion
boolean

The code module version is faulty (true) or not (false).

instanceName
string

The name of the instance.

moduleVersion
string

The version of the code module.

The PluginInfo object

OneAgent plugin.

Element
Type
Description
instances

A list of instances of the plugin.

pluginName
string

The name of the plugin.

The PluginInstance object

An instance of the OneAgent plugin.

Element
Type
Description
pluginVersion
string

The version of the plugin.

state
string

The state of the plugin instance.

Response body JSON model

{
  "hosts": [
    {
      "active": true,
      "autoUpdateSetting": "ENABLED",
      "availabilityState": "CRASHED",
      "availableVersions": [
        "string"
      ],
      "configuredMonitoringEnabled": true,
      "configuredMonitoringMode": "CLOUD_INFRASTRUCTURE",
      "currentActiveGateId": 1,
      "currentActiveGateIds": [
        "string"
      ],
      "currentNetworkZoneId": "string",
      "detailedAvailabilityState": "CRASHED_FAILURE",
      "faultyVersion": true,
      "hostInfo": {
        "agentVersion": {
          "major": 1,
          "minor": 1,
          "revision": 1,
          "sourceRevision": "string",
          "timestamp": "string"
        },
        "amiId": "string",
        "autoInjection": "DISABLED_MANUALLY",
        "autoScalingGroup": "string",
        "awsInstanceId": "string",
        "awsInstanceType": "string",
        "awsNameTag": "string",
        "awsSecurityGroup": [
          "string"
        ],
        "azureComputeModeName": "DEDICATED",
        "azureEnvironment": "string",
        "azureHostNames": [
          "string"
        ],
        "azureResourceGroupName": "string",
        "azureResourceId": "string",
        "azureSiteNames": [
          "string"
        ],
        "azureSku": "BASIC",
        "azureVmName": "string",
        "azureVmScaleSetName": "string",
        "azureVmSizeLabel": "string",
        "azureZone": "string",
        "beanstalkEnvironmentName": "string",
        "bitness": "32bit",
        "boshAvailabilityZone": "string",
        "boshDeploymentId": "string",
        "boshInstanceId": "string",
        "boshInstanceName": "string",
        "boshName": "string",
        "boshStemcellVersion": "string",
        "cloudPlatformVendorVersion": "string",
        "cloudType": "AZURE",
        "consumedHostUnits": "string",
        "cpuCores": 1,
        "customizedName": "string",
        "discoveredName": "string",
        "displayName": "string",
        "entityId": "string",
        "esxiHostName": "string",
        "firstSeenTimestamp": 1,
        "fromRelationships": {
          "isNetworkClientOfHost": [
            "string"
          ]
        },
        "gceInstanceId": "string",
        "gceInstanceName": "string",
        "gceMachineType": "string",
        "gceProject": "string",
        "gceProjectId": "string",
        "gcePublicIpAddresses": [
          "string"
        ],
        "gcpZone": "string",
        "hostGroup": {
          "meId": "string",
          "name": "string"
        },
        "hypervisorType": "AHV",
        "ipAddresses": [
          "string"
        ],
        "isMonitoringCandidate": true,
        "kubernetesCluster": "string",
        "kubernetesLabels": {},
        "kubernetesNode": "string",
        "lastSeenTimestamp": 1,
        "localHostName": "string",
        "localIp": "string",
        "logicalCpuCores": 1,
        "logicalCpus": 1,
        "managementZones": [
          {
            "description": "Dynatrace entity for the REST API example",
            "id": "6a98d7bc-abb9-44f8-ae6a-73e68e71812a",
            "name": "Dynatrace entity"
          }
        ],
        "monitoringMode": "FULL_STACK",
        "networkZoneId": "string",
        "oneAgentCustomHostName": "string",
        "openStackInstaceType": "string",
        "openstackAvZone": "string",
        "openstackComputeNodeName": "string",
        "openstackProjectName": "string",
        "openstackSecurityGroups": [
          "string"
        ],
        "openstackVmName": "string",
        "osArchitecture": "ARM",
        "osType": "AIX",
        "osVersion": "string",
        "paasAgentVersions": [
          {}
        ],
        "paasMemoryLimit": 1,
        "paasType": "AWS_ECS_EC2",
        "publicHostName": "string",
        "publicIp": "string",
        "scaleSetName": "string",
        "simultaneousMultithreading": 1,
        "softwareTechnologies": [
          {
            "edition": "string",
            "type": "string",
            "version": "string"
          }
        ],
        "tags": [
          {
            "context": "AWS",
            "key": "string",
            "value": "string"
          }
        ],
        "toRelationships": {
          "isNetworkClientOfHost": [
            "string"
          ],
          "isProcessOf": [
            "string"
          ],
          "isSiteOf": [
            "string"
          ],
          "runsOn": [
            "string"
          ]
        },
        "userLevel": "NON_SUPERUSER",
        "virtualCpus": 1,
        "vmwareName": "string",
        "zosCPUModelNumber": "string",
        "zosCPUSerialNumber": "string",
        "zosLpaName": "string",
        "zosSystemName": "string",
        "zosTotalGeneralPurposeProcessors": 1,
        "zosTotalPhysicalMemory": 1,
        "zosTotalZiipProcessors": 1,
        "zosVirtualization": "string"
      },
      "modules": [
        {
          "instances": [
            {
              "active": true,
              "faultyVersion": true,
              "instanceName": "string",
              "moduleVersion": "string"
            }
          ],
          "moduleType": "APACHE"
        }
      ],
      "monitoringType": "CLOUD_INFRASTRUCTURE",
      "plugins": [
        {
          "instances": [
            {
              "pluginVersion": "string",
              "state": "string"
            }
          ],
          "pluginName": "string"
        }
      ],
      "unlicensed": true,
      "updateStatus": "INCOMPATIBLE"
    }
  ],
  "nextPageKey": "string",
  "percentageOfEnvironmentSearched": 1
}

Related topics