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.
GET | SaaS | https://{your-environment-id}.live.dynatrace.com/api/v1/oneagents |
Environment ActiveGate | https://{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
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.
The start timestamp of the requested timeframe, in milliseconds (UTC).
If not set, then 72 hours behind from now is used.
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).
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
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
.
Filters result to the specified hosts only.
To specify several hosts use the following format: entity=ID1&entity=ID2
.
Only return hosts that are part of the specified management zone.
Specify the management zone ID here.
Only return hosts that are part of the specified management zone.
Specify the management zone name here.
If the managementZoneId parameter is set, this parameter is ignored.
Filters the resulting set of hosts by the specified network zone.
Specify the Dynatrace entity ID of the required network zone. You can fetch the list of available network zones with the GET all network zones call.
Filters the resulting set of hosts by the specified host group.
Specify the Dynatrace entity ID of the required host group.
Filters the resulting set of hosts by the specified host group.
Specify the name of the required host group.
Filters the resulting set of hosts by the OS type.
AIX
DARWIN
HPUX
LINUX
SOLARIS
WINDOWS
ZOS
Filters the resulting set of hosts by the cloud type.
AZURE
EC2
GOOGLE_CLOUD_PLATFORM
OPENSTACK
ORACLE
UNRECOGNIZED
Filters the resulting set of hosts by the auto-injection status.
DISABLED_MANUALLY
DISABLED_ON_INSTALLATION
DISABLED_ON_SANITY_CHECK
ENABLED
FAILED_ON_INSTALLATION
Filters the resulting set of hosts by the availability state of OneAgent.
MONITORED
: Hosts where OneAgent is enabled and active.UNMONITORED
: Hosts where OneAgent is disabled and inactive.CRASHED
: Hosts where OneAgent has returned a crash status code.LOST
: Hosts where it is impossible to establish connection with OneAgent.PRE_MONITORED
: Hosts where OneAgent is being initialized for monitoring.SHUTDOWN
: Hosts where OneAgent is shutting down in a controlled process.UNEXPECTED_SHUTDOWN
: Hosts where OneAgent is shutting down in an uncontrolled process.UNKNOWN
: Hosts where the state of OneAgent is unknown.
CRASHED
LOST
MONITORED
PRE_MONITORED
SHUTDOWN
UNEXPECTED_SHUTDOWN
UNKNOWN
UNMONITORED
Filters the resulting set of hosts by the detailed availability state of OneAgent.
UNKNOWN
: Hosts where the state of OneAgent is unknown.PRE_MONITORED
: Hosts where OneAgent is being initialized for monitoring.CRASHED_UNKNOWN
: Hosts where OneAgent has crashed for unknown reason.CRASHED_FAILURE
: Hosts where OneAgent has returned a crash status code.LOST_UNKNOWN
: Hosts where it is impossible to establish connection with OneAgent for unknown reason.LOST_CONNECTION
: Hosts where OneAgent has been recognized to be inactive.LOST_AGENT_UPGRADE_FAILED
: Hosts where OneAgent has a potential update problem due to inactivity after update.SHUTDOWN_UNKNOWN_UNEXPECTED
: Hosts where OneAgent is shutting down in an uncontrolled process.SHUTDOWN_UNKNOWN
: Hosts where OneAgent has shutdown for unknown reason.SHUTDOWN_GRACEFUL
: Hosts where OneAgent has shutdown because of host shutdown.SHUTDOWN_STOPPED
: Hosts where OneAgent has shutdown because the host has stopped.SHUTDOWN_AGENT_LOST
: Hosts where PaaS module has been recognized to be inactive.SHUTDOWN_SPOT_INSTANCE
: Hosts where OneAgent shutdown was triggered by the AWS Spot Instance interruption.SHUTDOWN_K8S_NODE_SHUTDOWN
: Hosts where OneAgent shutdown was triggered by a k8s node graceful shutdown.UNMONITORED_UNKNOWN
: Hosts where OneAgent is disabled and inactive for unknown reason.UNMONITORED_TERMINATED
: Hosts where OneAgent has terminated.UNMONITORED_DISABLED
: Hosts where OneAgent has been disabled in configuration.UNMONITORED_AGENT_STOPPED
: Hosts where OneAgent is stopped.UNMONITORED_AGENT_RESTART_TRIGGERED
: Hosts where OneAgent is being restarted.UNMONITORED_AGENT_UNINSTALLED
: Hosts where OneAgent is uninstalled.UNMONITORED_AGENT_DISABLED
: Hosts where OneAgent reported that it was disabled.UNMONITORED_AGENT_UPGRADE_FAILED
: Hosts where OneAgent has a potential update problem.UNMONITORED_ID_CHANGED
: Hosts where OneAgent has potentially changed ID during update.UNMONITORED_AGENT_LOST
: Hosts where OneAgent has been recognized to be unavailable due to server communication issues.UNMONITORED_AGENT_UNREGISTERED
: Hosts where a code module has been recognized to be unavailable because of shutdown.UNMONITORED_AGENT_VERSION_REJECTED
: Hosts where OneAgent was rejected because the version does not meet the minimum agent version requirement.MONITORED
: Hosts where OneAgent is enabled and active.MONITORED_ENABLED
: Hosts where OneAgent has been enabled in configuration.MONITORED_AGENT_REGISTERED
: Hosts where the new OneAgent has been recognized.MONITORED_AGENT_UPGRADE_STARTED
: Hosts where OneAgent has shutdown due to an update.MONITORED_AGENT_ENABLED
: Hosts where OneAgent reported that it was enabled.MONITORED_AGENT_VERSION_ACCEPTED
: Hosts where OneAgent was accepted because the version meets the minimum agent version requirement.
CRASHED_FAILURE
CRASHED_UNKNOWN
LOST_AGENT_UPGRADE_FAILED
LOST_CONNECTION
LOST_UNKNOWN
MONITORED
MONITORED_AGENT_ENABLED
MONITORED_AGENT_REGISTERED
MONITORED_AGENT_UPGRADE_STARTED
MONITORED_AGENT_VERSION_ACCEPTED
MONITORED_ENABLED
PRE_MONITORED
SHUTDOWN_AGENT_LOST
SHUTDOWN_GRACEFUL
SHUTDOWN_K8S_NODE_SHUTDOWN
SHUTDOWN_SPOT_INSTANCE
SHUTDOWN_STOPPED
SHUTDOWN_UNKNOWN
SHUTDOWN_UNKNOWN_UNEXPECTED
UNKNOWN
UNMONITORED_AGENT_DISABLED
UNMONITORED_AGENT_LOST
UNMONITORED_AGENT_RESTART_TRIGGERED
UNMONITORED_AGENT_STOPPED
UNMONITORED_AGENT_UNINSTALLED
UNMONITORED_AGENT_UNREGISTERED
UNMONITORED_AGENT_UPGRADE_FAILED
UNMONITORED_AGENT_VERSION_REJECTED
UNMONITORED_DISABLED
UNMONITORED_ID_CHANGED
UNMONITORED_TERMINATED
UNMONITORED_UNKNOWN
Filters the resulting set of hosts by monitoring mode of OneAgent deployed on the host.
CLOUD_INFRASTRUCTURE
DISCOVERY
FULL_STACK
STANDALONE
Filters the resulting set of hosts to those that have a certain OneAgent version deployed on the host.
Specify the comparison operator here.
EQUAL
GREATER
GREATER_EQUAL
LOWER
LOWER_EQUAL
Filters the resulting set of hosts to those that have a certain OneAgent version deployed on the host.
Specify the version in the <major>.<minor>.<revision>
format, for example 1.182.0
. You can fetch the list of available versions with the GET available versions call.
Filters the resulting set of hosts by the actual state of the auto-update setting of deployed OneAgents.
ENABLED
DISABLED
Filters the resulting set of hosts by the update status of OneAgent deployed on the host.
INCOMPATIBLE
OUTDATED
SCHEDULED
SUPPRESSED
UNKNOWN
UP2DATE
UPDATE_IN_PROGRESS
UPDATE_PENDING
UPDATE_PROBLEM
Filters the resulting set of hosts to those that run OneAgent version that is marked as faulty.
Filters the resulting set of hosts to those that run OneAgent that are unlicensed.
Example: Your Dynatrace license is missing the required "Foundation & Discovery" DPS capability for Discovery mode.
Filters the resulting set of hosts to those that are currently connected to the ActiveGate with the specified ID.
Use DIRECT_COMMUNICATION keyword to find the hosts not connected to any ActiveGate.
Filters the resulting set of hosts to those that run the specified OneAgent code module.
If several code module filters are specified, the code module has to match all the filters.
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
Filters the resulting set of hosts to those that have a certain code module version deployed on the host.
Specify the comparison operator here.
If several code module filters are specified, the code module has to match all the filters.
EQUAL
GREATER
GREATER_EQUAL
LOWER
LOWER_EQUAL
Filters the resulting set of hosts to those that have a certain code module version deployed on the host.
Specify the version in the <major>.<minor>.<revision>
format, for example 1.182.0
. You can fetch the list of available versions with the GET available versions call.
If several code module filters are specified, the code module has to match all the filters.
Filters the resulting set of hosts to those that run the code module version that is marked as faulty.
If several code module filters are specified, the code module has to match all the filters.
Filters the resulting set of hosts to those that run the plugin with the specified name.
The CONTAINS operator is applied to the specified value.
If several plugin filters are specified, the plugin has to match all the filters.
Filters the resulting set of hosts to those that have a certain plugin version deployed on the host.
Specify the comparison operator here.
If several plugin filters are specified, the plugin has to match all the filters.
EQUAL
GREATER
GREATER_EQUAL
LOWER
LOWER_EQUAL
Filters the resulting set of hosts to those that have a certain plugin version deployed on the host.
Specify the version in the <major>.<minor>.<revision>
format, for example 1.182.0
. You can fetch the list of available versions with the GET available versions call.
<minor>
and <revision>
parts of the version number are optional.
If several plugin filters are specified, the plugin has to match all the filters.
Filters the resulting set of hosts to those that run the plugin with the specified state.
DISABLED
ERROR_AUTH
ERROR_COMMUNICATION_FAILURE
ERROR_CONFIG
ERROR_TIMEOUT
ERROR_UNKNOWN
INCOMPATIBLE
LIMIT_REACHED
NOTHING_TO_REPORT
OK
STATE_TYPE_UNKNOWN
UNINITIALIZED
UNSUPPORTED
WAITING_FOR_STATE
The cursor for the next page of results, if results do not fit on one page. You can find the cursor value on the current page of the response, in the nextPageKey field.
To obtain subsequent pages, you must specify this cursor value in your query, and keep all other query parameters as they were in the original request.
If you don't specify the cursor, the first page will always be returned.
Response
Response codes
Response body objects
The HostsListPage
object
A list of hosts with OneAgent deployment information for each host.
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.
The progress of the environment search, in percent.
The HostAgentInfo
object
OneAgent deployment on a host.
OneAgent is active (true
) or inactive (false
).
The effective auto-update setting of OneAgent. For host with inherited configuration it is calculated from its parent's configuration
ENABLED
DISABLED
The availability state of OneAgent.
CRASHED
LOST
MONITORED
PRE_MONITORED
SHUTDOWN
UNEXPECTED_SHUTDOWN
UNKNOWN
UNMONITORED
A list of versions OneAgent can be updated to.
Monitoring is enabled (true
) or disabled (false
) in the OneAgent configuration.
Configured monitoring mode of OneAgent.
CLOUD_INFRASTRUCTURE
DISCOVERY
FULL_STACK
DEPRECATED
This field is deprecated and provided for backward compatibility.
Use the currentActiveGateIds field instead.
The list of ActiveGate IDs of ActiveGates to which OneAgent is currently connected.
The ID of the network zone that OneAgent is using.
The detailed availability state of OneAgent.
CRASHED_FAILURE
CRASHED_UNKNOWN
LOST_AGENT_UPGRADE_FAILED
LOST_CONNECTION
LOST_UNKNOWN
MONITORED
MONITORED_AGENT_ENABLED
MONITORED_AGENT_REGISTERED
MONITORED_AGENT_UPGRADE_STARTED
MONITORED_AGENT_VERSION_ACCEPTED
MONITORED_ENABLED
PRE_MONITORED
SHUTDOWN_AGENT_LOST
SHUTDOWN_GRACEFUL
SHUTDOWN_K8S_NODE_SHUTDOWN
SHUTDOWN_SPOT_INSTANCE
SHUTDOWN_STOPPED
SHUTDOWN_UNKNOWN
SHUTDOWN_UNKNOWN_UNEXPECTED
UNKNOWN
UNMONITORED_AGENT_DISABLED
UNMONITORED_AGENT_LOST
UNMONITORED_AGENT_RESTART_TRIGGERED
UNMONITORED_AGENT_STOPPED
UNMONITORED_AGENT_UNINSTALLED
UNMONITORED_AGENT_UNREGISTERED
UNMONITORED_AGENT_UPGRADE_FAILED
UNMONITORED_AGENT_VERSION_REJECTED
UNMONITORED_DISABLED
UNMONITORED_ID_CHANGED
UNMONITORED_TERMINATED
UNMONITORED_UNKNOWN
OneAgent version is faulty (true
) or not (false
).
The monitoring mode of OneAgent.
CLOUD_INFRASTRUCTURE
DISCOVERY
FULL_STACK
STANDALONE
OneAgent is unlicensed.
The current update status of OneAgent.
INCOMPATIBLE
OUTDATED
SCHEDULED
SUPPRESSED
UNKNOWN
UP2DATE
UPDATE_IN_PROGRESS
UPDATE_PENDING
UPDATE_PROBLEM
The Host
object
Information about the host.
Status of auto-injection
DISABLED_MANUALLY
DISABLED_ON_INSTALLATION
DISABLED_ON_SANITY_CHECK
ENABLED
FAILED_ON_INSTALLATION
The name inherited from AWS.
DEDICATED
SHARED
BASIC
DYNAMIC
FREE
PREMIUM
SHARED
STANDARD
32bit
64bit
The Cloud Foundry BOSH availability zone.
The Cloud Foundry BOSH deployment ID.
The Cloud Foundry BOSH instance ID.
The Cloud Foundry BOSH instance name.
The Cloud Foundry BOSH name.
The Cloud Foundry BOSH stemcell version.
Defines the cloud platform vendor version.
AZURE
EC2
GOOGLE_CLOUD_PLATFORM
OPENSTACK
ORACLE
UNRECOGNIZED
The customized name of the entity
The discovered name of the entity
The name of the Dynatrace entity as displayed in the UI.
The Dynatrace entity ID of the required entity.
The timestamp of when the entity was first detected, in UTC milliseconds
The Google Compute Engine instance ID.
The Google Compute Engine instance name.
The Google Compute Engine machine type.
The Google Compute Engine project.
The Google Compute Engine numeric project ID.
The public IP addresses of the Google Compute Engine.
The Google Cloud Platform Zone.
AHV
AWS_NITRO
GVISOR
HYPERV
KVM
LPAR
QEMU
UNRECOGNIZED
VIRTUALBOX
VMWARE
WPAR
XEN
The kubernetes cluster the entity is in.
The kubernetes labels defined on the entity.
The kubernetes node the entity is in.
The timestamp of when the entity was last detected, in UTC milliseconds
The AIX instance logical CPU count.
FULL_STACK
INFRASTRUCTURE
OFF
The ID of network zone the entity is in.
The custom name defined in OneAgent config.
ARM
IA64
PARISC
PPC
PPCLE
S390
SPARC
X86
ZOS
AIX
DARWIN
HPUX
LINUX
SOLARIS
WINDOWS
ZOS
AWS_ECS_EC2
AWS_ECS_FARGATE
AWS_LAMBDA
AZURE_FUNCTIONS
AZURE_WEBSITES
CLOUD_FOUNDRY
GOOGLE_APP_ENGINE
GOOGLE_CLOUD_RUN
HEROKU
KUBERNETES
OPENSHIFT
The AIX instance simultaneous threads count.
NON_SUPERUSER
NON_SUPERUSER_STRICT
SUPERUSER
The AIX instance virtual CPU count.
The CPU model number.
The CPU serial number.
Name of the LPAR.
Name of the system.
Number of assigned processors for this LPAR.
Memory assigned to the host (Terabyte).
Number of assigned support processors for this LPAR.
Type of virtualization on the mainframe.
The AgentVersion
object
Defines the version of the agent currently running on the entity.
The major version number.
The minor version number.
The revision number.
A string representation of the SVN revision number.
A timestamp string: format "yyyymmdd-hhmmss
The HostGroup
object
The Dynatrace entity ID of the host group.
The name of the Dynatrace entity, displayed in the UI.
The EntityShortRepresentation
object
The short representation of a Dynatrace entity.
A short description of the Dynatrace entity.
The ID of the Dynatrace entity.
The name of the Dynatrace entity.
The TechnologyInfo
object
The TagInfo
object
Tag of a Dynatrace entity.
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
The key of the tag.
Custom tags have the tag value here.
The value of the tag.
Not applicable to custom tags.
The ModuleInfo
object
OneAgent code module.
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.
The code module instance is active (true
) or inactive (false
).
The code module version is faulty (true
) or not (false
).
The name of the instance.
The version of the code module.
The PluginInfo
object
OneAgent plugin.
The name of the plugin.
The PluginInstance
object
An instance of the OneAgent plugin.
The version of the plugin.
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}