Header background

Automate complex metric-related use cases with the Metrics API version 2

Dynatrace offers numerous built-in metrics that provide high observability into your monitoring environment. We're happy to announce the GA release of Metrics API v2, a single interface for all your metric-related use cases and integration scenarios.

Dynatrace collects a huge number of metrics for each OneAgent-monitored host in your environment. Depending on the types of technologies you’re running on individual hosts, the average number of metrics is about 500 per computational node. Besides all the metrics that originate from your hosts, Dynatrace also collects all the important key performance metrics for services and real-user monitored applications as well as cloud platform metrics from AWS, Azure, and Cloud Foundry.

The Dynatrace Metrics API has long enabled API consumers to query individual metrics for the implementation of external use cases. Some of the most popular ones we see among our customers are:

  • Monitoring metrics in build pipelines for remediation efforts.
  • Running metric queries on a subset of entities for live monitoring and system overviews.
  • Creating customized metric reports.

Welcome to Dynatrace Metrics API version 2

We’re happy to announce an updated version of our Metrics API, which provides:

  • Ease of use and improved developer experience.
  • Combined entity and metric queries with generic and reusable selectors.
  • A powerful query layer for time series data that introduces the concept of metric transformations.
  • RESTful endpoints for metric discovery and querying.

The Metrics API v2 is the first v2 API available in Dynatrace. These APIs deliver a consistent developer experience by providing a set of common features for all endpoints.

A single API interface for all your metric use cases

With the new Metrics API v2, you can access all your metrics over a single interface. In addition to built-in metrics, you can extend your metric repository with calculated or custom metrics. The interface enables complete visibility into all your metrics, and all metrics can be queried through the same, powerful query layer.

The new API allows you to realize use cases in reporting and data analytics and to further integrate custom applications with Dynatrace. Dynatrace Keptn, for example, uses the new Metrics API v2 to monitor the outcomes of application deployment.

Metrics API v2 is designed in a RESTful way to allow you to discover which metrics are available, retrieve metadata, and to execute sophisticated time series queries.

  • GET /metrics
  • GET /metrics/{metricId}
  • POST /metrics/query

These endpoints are feature packed and enable you to get all things done around metrics while keeping things simple.

Early Adopter endpoint deprecation

Important: The Early Adopter Metrics API v2 endpoints are being deprecated with this GA release. While in the deprecation phase, they’ll still be available and function but won’t receive additional updates or features.

  • /metrics/series (Deprecated—available until September 2020)
  • /metrics/descriptors (Deprecated—available until September 2020)

Discover metrics with the /metrics endpoint

Search and discover all metrics stored in Dynatrace

The Metrics API is the consolidated interface for discovering and querying all metrics stored in Dynatrace. Using our new API selectors, you can easily browse the metric hierarchy using wildcards. You can also perform a free-text search to fetch all metrics that share a common keyword.

The metric registry is based on a hierarchical tree that contains all metrics. Depending on the origin of a metric, different namespaces are used. Currently, the following namespaces exist:

  • builtin—Built-in metrics
  • calc—Calculated metrics
  • ext—Extension or plugin metrics

Example 1: Fetch a list of all host metrics

/metrics?metricSelector=builtin:host.*

Example 2: Fetch a list of all metrics that contain the keyword cpu

/metrics?text=cpu

Refine your query result by using transformations

Every metric has a list of available transformations that you can apply to refine your query result. There are different types of metric transformations and aggregations available per metric.

  • Dimension augmentation—Enriches the result set with additional dimensions.
  • Dimension mapping—Changes the dimensions of your result set by splitting or merging.
  • Dimension filtering—Filters dimension values and either keeps or rejects data based on the filter criteria.
  • Payload aggregation—Changes how numeric values are calculated in the result set.

So you can discover which transformations and aggregations are available, the /metrics endpoint provides the transformations and aggregationTypes metadata fields for each metric. Information about transformations and aggregations gathered from the /metrics endpoint can then be used, for example, in a custom query builder integration where metric data can be iteratively transformed to deliver the desired result set.

For more information, please see our documentation for metric transformations and aggregations.

Easily access all metadata for a selected metric

Every metric has metadata properties that are important for efficiently querying data. The /metrics/{metricId} endpoint delivers the complete metadata set for a selected metric, and the response contains both general information about the metric as well as query-relevant fields.

This metadata is valuable in understanding the query possibilities of specific metrics (see the sample output below). For example, the information presented can be used to build an online metric browser.

{

      "metricId": "builtin:host.cpu.user ",
      "displayName": "CPU user",
      "description": "Percentage of user-space CPU time currently utilized",
      "unit": "Percent",
      "aggregationTypes": [
        "auto",
        "avg",
        "max",
        "min"
      ],
      "transformations": [
        "filter",
        "fold",
        "merge",
        "names",
        "parents"
      ],
      "defaultAggregation": {
        "type": "avg"
      },
      "dimensionDefinitions": [
        {
          "name": "primary",
          "type": "ENTITY"
        }
     ]
}

You can also use the /metrics/{metricId} endpoint to request a transformed metric as each transformed metric request yields a new metric with the same metadata fields available:

GET /metrics/builtin:host.cpu.user:merge(0):max:fold

This enables you to use the same interface for raw and transformed metrics. Whenever you work on a query and apply transformations to a metric, you can use the endpoint to crosscheck the definition of the transformed metric (such as shown above).

Retrieve time series data with /metrics/query

After you’ve discovered the right metrics to use, it’s time to query the time series data. The query endpoint comes with a powerful query language that allows you to retrieve your time series data for different aggregations and for specific timeframes. For a detailed explanation of all its capabilities, review Dynatrace Help.

Prepare your query

The query endpoint provides all the functionality for querying time series data for both raw and transformed metrics.

In each request, you can query time series data for up to 10 different metrics based on relative and absolute dates, different time resolutions, and for specific selections of entities.

Example 1: Query disk availability for all hosts with hourly resolution for the default query timeframe of two weeks

/metrics/query?metricSelector=builtin:host.disk.avail:names&resolution=h

Example 2: Query for session duration aggregated by user type and application for the last two hours

/metrics/query?metricSelector=builtin:apps.web.sessionDuration:merge(Users)&resolution=10m&from=now-2h&to=now

Narrow down the result with an entitySelector

The entitySelector is a new concept in our Environment API version 2. Selectors allow you to formulate a resource-specific query. For example, you can narrow down an entity result set with the entitySelector. The selector can be also plugged in to other endpoints that support it, like the /metrics endpoint, without being changed. This increases the interplay between endpoints when working with multiple resources at once; you formulate a resource query once, and, after that, it’s just a matter of copy and paste.

Example 1: Query disk availability only for hosts in a specific management zone

/metrics/query?metricSelector=builtin:host.disk.avail:names&resolution=h&entitySelector=type(HOST),mz(production)

Example 2: Query the average Apdex for mobile apps aggregated by app and operating system for the last two hours

The entitySelector is used to query all mobile apps with the tag myTag1; the metricSelector aggregates data for the last two hours by app and operating system.

/metrics/query?metricSelector=builtin:apps.other.apdex.osAndVersion:merge(App Version):names:avg&resolution=h&from=now-2h&to=now&entitySelector=type(MOBILE_APPLICATION),tag(myTag1)

Query result sample

The response of the /metrics/query endpoint provides you the requested time series data with the selected aggregation, split by dimensions. The default is 100 time series per page if not overwritten in the query parameter. If the result set is larger than the page size, the nextPageKey is set in the response to retrieve the next page of the result set.

{
  "totalCount": 3,
  "nextPageKey": "ABCDEFABCDEFABCDEF_",
  "result": [
    {
      "metricId": "builtin:host.disk.avail",
      "data": [
        {
          "dimensions": [
            "HOST-F1266E1D0AAC2C3C",
            "DISK-F1266E1D0AAC2C3F"
          ],
          "timestamps": [
            3151435100000,
            3151438700000,
            3151442300000
          ],
          "values": [
            11.1,
            22.2,
            33.3
          ]
       }
    }
  ]
}

Need a metric in CSV format?

The query endpoint supports two response formats, JSON and CSV. By default, the response is presented in JSON format. If you need CSV-formatted output, you can easily set the Content-Type header in the request to “text/csv; header=present; charset=utf-8".

POST /api/v2/metrics/query?metricSelector=builtin:host.disk.avail
Authorization: Api-Token <token>'
Accept: text/csv; header=present; charset=utf-8
metricId,Operating system,Geolocation,time,value
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:37:00,
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:38:00,0.64
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:39:00,0.69
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:40:00,0.71
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:41:00,0.75
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:42:00,0.5
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:43:00,
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:44:00,0.5
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:45:00,0.5
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:46:00,
builtin:apps.other.apdex.osAndGeo:merge(0),OS-472A4A3B41095B09,GEOLOCATION-274673B255FE5CF0,2020-01-30 15:47:00,

Feedback and what’s next

The new Dynatrace Metrics REST API v2 comes with many improvements that have been requested by Dynatrace customers. It offers great convenience in discovering metrics and building sophisticated metric queries at scale.

The Metrics API v2 provides a very powerful interface for metric discovery and queries, and we’ll complement it with an overhaul of our external metric ingestion soon. With the new ingestion, it will be easier to import metrics into Dynatrace in a flexible and seamless way—stay tuned for more this year.

Also stay tuned for other version 2 APIs that will be available later this year, including/v2/entities and /v2/problems.

As always, we want to hear from you regarding what’s working or not working for you. Please share your feedback with us at Dynatrace answers.