Timeseries API

https://{id}.live.dynatrace.com/api/v1/timeseries

The timeseries endpoint delivers metrics that Dynatrace collects from the different monitored entities over time. This endpoint is used to read metrics, such as CPU usage, for selected entities over a given timeframe. By passing additional parameters this endpoint allows you to filter the selected timeseries for entity types and to specify what type of result aggregation the result should contain.

GET parameters

The timeseries endpoint allows the following parameters to be sent as HTTP GET requests. Note that to get a valid result the request has to either use relativeTime or startTimestamp and endTimestamp. The maximum allowed queryable timeframe is 6 months:

  • timeseriesId - Case-sensitive identifier for the specific timeseries that should be returned (for example, com.dynatrace.builtin:host.cpu.load). The prefix com.dynatrace.builtin: identifies timeseries that are directly built into Dynatrace, while user-defined prefixes can be used to identify custom metrics timeseries that are introduced by custom monitoring plugins (e.g., JMX metrics). You can find a list of available built-in Dynatrace timeseries in the Timeseries ID Table.
  • startTimestamp (optional) - Start timestamp of the requested timeframe, given in milliseconds (UTC). The start timestamp must be smaller (earlier) than the endtime stamp.
  • endTimestamp (optional) - End timestamp of the requested timeframe, given in milliseconds (UTC). End timestamp must be larger (later) than the startTimestamp. If endTimestamp is larger than the actual time, Dynatrace automatically uses actual time instead.
  • relativeTime (optional) - Instead of using timestamps for selecting a timeframe it is possible to specify ‘hour’ to receive the timeseries data for the last hour. Allowed values are ‘hour’, ‘2hours’, ‘6hours’, ‘day’, ‘week’ and ‘month’;
  • queryMode (optional) - Defines the type of result that the call should return. Valid result modes are ‘series’ for receiving the entire timeseries as data points or ‘total’ for receiving one scalar value for the requested timeframe. The default query mode returns a series of data points.
  • aggregationType - Defines which aggregation type is used for the resulting timeseries. Valid aggregation types are min, max, avg, sum, median, and count.
  • entity (optional) - Defines which entity should deliver the requested timeseries. You can find the specific entity ID by opening the corresponding Dynatrace entity page where the unique ID is displayed within the URL (for example, HOST-B64B6B1BB11E2244). If the selected entity doesn’t support the requested timeseries, the request will result in an error.

POST payload

For instances where a simple entity query isn’t sufficient, Dynatrace offers additional filters as HTTP POST requests. All previously defined HTTP GET parameters can be used within a HTTP POST JSON payload along with the following additional parameters:

  • entities - Defines a set of entity identifiers that should be included in the result. The semantics are the same as with the entity parameter except that the set can contain more than one entity ID. The entities set replaces the entity parameter. So the entity parameter isn’t allowed within HTTP POSTs.
  • filters - The filters parameter contains a map of filter keys and values, where valid filter keys are:
filter key values
processType see Process types
osType see OS types
serviceType see Service types
technology see Technology types
webServiceName individual name
webServiceNamespace individual name
host your specific host ids, e.g. HOST-B64B6B1BB11E2244

Result

Query results are returned as JSON payloads that either contain the data points of the requested timeseries or a scalar result if the request set the queryMode=total parameter to receive totals instead of a timeseries. The result payload also contains attributes describing the unit (unit) of the returned data points, the result resolution (resolutionInMillisUTC) of the series and the selected type of aggregation (aggregationType).
An example payload is shown below:

{
"result":
  {
  "dataPoints":
    {
    "HOST-B64B6B9CB11E2244":
    [
    [1443418260000,36.186815897623696],
    [1443418320000,31.984347025553387],
    [1443418380000,36.897412618001304],
    [1443418440000,33.65802764892578],
    ...
    ]
    },
  "timeseriesId":"com.dynatrace.builtin:host.cpu.user",
  "unit":"Percent",
  "entities":{"HOST-B64B6B9CB11E2244":"L-W8-64-APMDay3"},
  "resolutionInMillisUTC":60000,
  "aggregationType":"AVG"
  }
}

Examples

The following examples show how to fetch detailed timeseries from the host-, application-, and service levels using the Dynatrace API. To execute these examples in your environment, replace the {id} placeholder with your own Dynatrace environment ID, replace the Api-Token with your own generated token, and replace the specific host entity ID HOST-B64B6B9CB11E2244 with one of your own host entity IDs.

fetch the average user CPU of a given host

This example uses the HTTP authorization header to authenticate a request to read the timeseries with the ID com.dynatrace.builtin:host.cpu.user for a given host HOST-B64B6B1BB11E2244. The result returns an average for each timespan.

curl -L -H "Authorization: Api-Token cw88t44BRk2KcJkdM419T" \
"https://{id}.live.dynatrace.com/api/v1/timeseries?relativeTime=hour&entity=HOST-B64B6B9CB11E2244&aggregationType=AVG&timeseriesId=com.dynatrace.builtin:host.cpu.user"   

JSON result

{
"result":
  {
  "dataPoints":
    {
    "HOST-B64B6B9CB11E2244":
    [
    [1443418260000,36.186815897623696],
    [1443418320000,31.984347025553387],
    [1443418380000,36.897412618001304],
    [1443418440000,33.65802764892578],
    ...
    ]
    },
  "timeseriesId":"com.dynatrace.builtin:host.cpu.user",
  "unit":"Percent",
  "entities":{"HOST-B64B6B9CB11E2244":"L-W8-64-APMDay3"},
  "resolutionInMillisUTC":60000,
  "aggregationType":"AVG"
  }
}

fetch the number of received bytes for all network interfaces of all Windows hosts

This example shows how to use a HTTP POST message along with a given HTTP authorization header to authenticate and fetch the total values of received bytes for all available network interfaces on all Windows hosts. The example uses a simple osType filter that reduces the result to Windows hosts only. The result returns the total avarages for all network interfaces.

curl -L -H "Authorization: Api-Token cw88t44BRk2KcJkdM419T" \
-H "Content-Type: application/json" \
"https://{id}.live.dynatrace.com/api/v1/timeseries/" \
-d "{\"relativeTime\":\"hour\",\"queryMode\":\"total\",\"timeseriesId\":\"com.dynatrace.builtin:host.nic.bytesreceived\",\"aggregationType\":\"AVG\",\"filters\":{\"osType\":\"windows\"}}"

JSON result

{
  "result":
  {
    "dataPoints":
    {
      "HOST-A3C4D3D278C161FA, NETWORK_INTERFACE-A3C4D3C725AB1AFA": [[1447653540000,0.0]],
      "HOST-A3C4D3D278C161FA, NETWORK_INTERFACE-A3C49B83CF7E8AC1":[[1447653540000,6368.994714355469]],
      "HOST-A3C4D3D278C161FA, NETWORK_INTERFACE-A3C4DBD25FC18D6F":[[1447653540000,0.0]]
    },
    "timeseriesId":"com.dynatrace.builtin:host.nic.bytesreceived",
    "unit":"BytePerSecond",
    "entities":{
        "NETWORK_INTERFACE-A3C4D3C725AB1AFA":"Hyper-V Virtual Ethernet Adapter#2",
        "NETWORK_INTERFACE-A3C4DBD25FC18D6F":"VirtualBox Host-Only Ethernet Adapter",
        "HOST-A3C4D3D278C161FA":"LNZ127481N02.clients.dynatrace.org",
        "NETWORK_INTERFACE-A3C49B83CF7E8AC1":"Intel(R) Dual Band Wireless-AC 7260"
    },
    "resolutionInMillisUTC":3610000,
    "aggregationType":"AVG"
  }
}

Aggregation types

Aggregation type
max
min
sum
avg
median
count

Available timeseries

timeseries id name unit aggregations filters
com.dynatrace.builtin:host.cpu.idle CPU idle % min, max, sum, avg osType
com.dynatrace.builtin:host.cpu.system CPU system % min, max, sum, avg osType
com.dynatrace.builtin:host.cpu.load CPU load % min, max, sum, avg osType
com.dynatrace.builtin:host.cpu.user CPU user % min, max, sum, avg osType
com.dynatrace.builtin:host.cpu.iowait CPU io wait % min, max, sum, avg osType
com.dynatrace.builtin:host.cpu.steal CPU steal % min, max, sum, avg osType
com.dynatrace.builtin:host.cpu.other CPU other % min, max, sum, avg osType
com.dynatrace.builtin:host.mem.available Memory available bytes min, max, sum, avg osType
com.dynatrace.builtin:host.mem.availablepercentage Memory percent available % min, max, sum, avg osType
com.dynatrace.builtin:host.mem.used Memory used bytes min, max, sum, avg osType
com.dynatrace.builtin:host.mem.pagefaults Page faults per second count min, max, sum, avg osType
com.dynatrace.builtin:host.nic.bytesreceived Network interface bytes received on osi bytes min, max, sum, avg osType
com.dynatrace.builtin:host.nic.bytessent Network interface bytes sent on osi bytes min, max, sum, avg osType
com.dynatrace.builtin:host.nic.packetsreceived Network interface packets received on osi count min, max, sum, avg osType
com.dynatrace.builtin:host.nic.packetssent Network interface packets sent on osi count min, max, sum, avg osType
com.dynatrace.builtin:host.nic.host.nic.packetsreceiveddropped Network interface dropped incoming packets count min, max, sum, avg osType
com.dynatrace.builtin:host.nic.host.nic.packetssentdropped Network interface dropped outgoing packets count min, max, sum, avg osType
com.dynatrace.builtin:host.nic.host.nic.packetsreceivederrors Network interface incoming packet errors count min, max, sum, avg osType
com.dynatrace.builtin:host.nic.host.nic.packetssenterrors Network interface outgoing packet errors count min, max, sum, avg osType
com.dynatrace.builtin:host.disk.bytesread Disk read bytes per second on Osi bytes/sec min, max, sum, avg osType
com.dynatrace.builtin:host.disk.byteswritten Disk write bytes per second on Osi bytes/sec min, max, sum, avg osType
com.dynatrace.builtin:host.disk.readoperations Disk read operations per second on Osi count/sec min, max, sum, avg osType
com.dynatrace.builtin:host.disk.writeoperations Disk write operations per second on Osi count/sec min, max, sum, avg osType
com.dynatrace.builtin:host.disk.readtime Disk read time on Osi ms min, max, sum, avg osType
com.dynatrace.builtin:host.disk.writetime Disk write time on Osi ms min, max, sum, avg osType
com.dynatrace.builtin:host.disk.queuelength Disk average queue length on Osi count min, max, sum, avg osType
com.dynatrace.builtin:host.disk.availablespace Disk available on Osi bytes min, max, sum, avg osType
com.dynatrace.builtin:host.disk.usedspace Disk used on Osi bytes min, max, sum, avg osType
com.dynatrace.builtin:pgi.cpu.usage Process group CPU usage % min, max, sum, avg processType, host
com.dynatrace.builtin:pgi.mem.usage Process group working set size bytes min, max, sum, avg processType, host
com.dynatrace.builtin:pgi.nic.bytesreceived Process group bytes received bytes min, max, sum, avg processType, host
com.dynatrace.builtin:pgi.nic.bytessent Process group bytes sent bytes min, max, sum, avg processType, host
com.dynatrace.builtin:pgi.responsiveness Process group server responsiveness µs min, max, sum, avg processType, host
com.dynatrace.builtin:pgi.workerprocesses Process group process count count min, max, sum, avg processType, host
com.dynatrace.builtin:service.requestspermin Requests count count count serviceType, technology, webServiceName, webServiceNamespace
com.dynatrace.builtin:service.responsetime Response time µs min, max, sum, avg serviceType, technology, webServiceName, webServiceNamespace
com.dynatrace.builtin:service.clientsidefailurerate Failure rate % min, max, sum, avg serviceType, technology, webServiceName, webServiceNamespace
com.dynatrace.builtin:service.serversidefailurerate Failure rate % min, max, sum, avg serviceType, technology, webServiceName, webServiceNamespace
com.dynatrace.builtin:servicemethod.requestspermin Requests count count count serviceType, technology, webServiceName, webServiceNamespace
com.dynatrace.builtin:servicemethod.responsetime Response time µs min, max, sum, avg serviceType, technology, webServiceName, webServiceNamespace
com.dynatrace.builtin:servicemethod.clientsidefailurerate Failure rate % min, max, sum, avg serviceType, technology, webServiceName, webServiceNamespace
com.dynatrace.builtin:servicemethod.serversidefailurerate Failure rate % min, max, sum, avg serviceType, technology, webServiceName, webServiceNamespace
com.dynatrace.builtin:app.useractionduration Action duration µs min, max, sum, avg serviceType
com.dynatrace.builtin:app.useractionsperminute Actions count count count serviceType
com.dynatrace.builtin:app.errorcount Error count count count serviceType
com.dynatrace.builtin:app.jserrorsduringuseractions Error count count count serviceType
com.dynatrace.builtin:app.jserrorswithoutuseractions Error count count count serviceType
com.dynatrace.builtin:appmethod.useractionduration Action duration µs min, max, sum, avg serviceType
com.dynatrace.builtin:appmethod.useractionsperminute Actions count count count serviceType
com.dynatrace.builtin:appmethod.errorcount Error count count count serviceType
com.dynatrace.builtin:host.availability host availability state   osType
com.dynatrace.builtin:pgi.availability process availability  state   processType
com.dynatrace.builtin:webcheck.availability WebCheck availability state    

Process types

The list of known process types we monitor with Dynatrace is continuously growing. If you don’t see a certain process type in the list below, please refer to the Dynatrace processes page and see if the process is included there.

Process type
unknown
linuxsystem
oracledb
apachehttp
windowssystem
windowsservice
mssql
db2
iis
mysql
java
dotnet
tomcat
websphere
apmng
jboss
weblogic
glassfish
iisapppool
postgres
mongodb
cassandra
memcached
couchdb
redis
ruby
perl
nodejs
python
nginx
varnishcache
haproxy
php
awsrds
erlang
dockerdaemon
mongodbrouter

OS types

The list of known operating systems that we monitor with Dynatrace is continuously growing. If you don’t see a certain OS type listed below, please refer to the Dynatrace hosts page and see if the OS type is included there.

OS type
unknown
windows
linux
hpux
aix
solaris
zos
darwin

Technology types

Technology type
unknown
java
dotnet
sdk
os
apache
wsmb
z
net
iis
php
nodejs
ruby
nginx
loganalytics
varnish

Service types

Service type
unknown
webrequest
webservice
database
method
website
messaging
mobile
process
rmi