Upgrade from classic service metrics to Grail

• Latest Dynatrace
• Upgrade guide
• 5-min read
• Updated on Aug 10, 2026

Use this guide to convert classic service metric selectors to Dynatrace Query Language (DQL) and understand how each service metric maps to its Grail equivalent.

Why upgrade?

What will you do?

Before you begin

Prerequisites

Prior knowledge

Metric mapping types

Typically, a metric on Grail is equivalent to a Metrics Classic metric. In some cases, however, there's no one-to-one relation.

How to upgrade

To upgrade from classic service metrics to Metrics on Grail

Convergent metrics

When a single Grail-based metric represents multiple Metrics Classic metrics, you can obtain comparable results for individual metric values through metric dimensions.

The sections below cover a group of related classic metrics, with a DQL example showing how to filter by the relevant dimension and a mapping table listing the classic keys. If you don't find the required classic metric key in the tables below, refer to Built-in Metrics on Grail.

HTTP 4xx and HTTP 5xx status codes

To convert the classic service metrics that track the rate of HTTP error responses, use the dt.service.request.count Grail-based metric filtered by http.response.status_code.

The following DQL queries return the rate of requests with HTTP response status code 5xx or 4xx—an equivalent of builtin:service.errors.fivexx.rate and builtin:service.errors.fourxx.rate.

DQL query example for 5xx status code

// calculate HTTP 5xx response status code request rate
timeseries {total = sum(dt.service.request.count), interval:1m}
| join [
  timeseries {fiveXX = sum(dt.service.request.count, default: 0.0), interval:1m},
  filter:http.response.status_code >= 500 and http.response.status_code <= 599
  ], kind:leftOuter, prefix: "httpState.", on:{ timeframe }
  | fieldsAdd {rate5xx = httpState.fiveXX[] / total[] * 100}
  | fields rate5xx, timeframe, interval

DQL query example for 4xx status code

// calculate HTTP 4xx response status code request rate
timeseries {total = sum(dt.service.request.count), interval:1m}
| join [
  timeseries {fourXX = sum(dt.service.request.count, default: 0.0), interval:1m},
  filter: http.response.status_code >= 400 and http.response.status_code<=499
  ], kind:leftOuter, prefix: "httpState.", on:{ timeframe }
| fieldsAdd {rate4xx = httpState.fourXX[] / total[] * 100}
| fields rate4xx, timeframe, interval

Mapping table

Failure and success

To convert the classic service metrics that track the count and rate of successful versus failed requests, use the dt.service.request.count Grail-based metric filtered by failed.

The following DQL query returns the count of successful requests to MY_SERVICE-00000—an equivalent of builtin:service.errors.total.successCount.

DQL query example

timeseries sum(dt.service.request.count), interval:1m,
    by:{dt.entity.service, failed},
    filter:{
      dt.entity.service == "<MY_SERVICE-00000>"
      and failed == false
    }

Mapping table

Failure and success of HTTP 4xx and HTTP 5xx

To convert the classic service metrics that track the count of HTTP 4xx and 5xx error responses and their complements (non-error requests), use the dt.service.request.count Grail-based metric filtered by failed and http.response.status_code.

The following DQL query returns the count of failed requests to MY_SERVICE-00000 with HTTP response status code 4xx—an equivalent of builtin:service.errors.fourxx.count.

DQL query example

timeseries sum(dt.service.request.count), interval:1m,
    by:{dt.entity.service, failed, http.response.status_code},
    filter:{
      dt.entity.service == "<MY_SERVICE-00000>"
      and failed == true
      and http.response.status_code >= 400
      and http.response.status_code <= 499
    }

Mapping table

Key requests

To convert classic service metrics related to key requests, use the dt.service.request.failure_count, dt.service.request.response_time, and dt.service.request.count Grail-based metrics filtered by different parameters.

The following DQL query example returns the total number of failed requests to /orange.jsf with HTTP response status code 5xx (equivalent of builtin:service.keyRequest.errors.fivexx.rate).

DQL query example

timeseries sum(dt.service.request.count), interval:1m,
    by:{endpoint.name, http.response.status_code},
    filter:{
      endpoint.name == "/orange.jsf"
      and http.response.status_code >= 500
      and http.response.status_code <= 599
    }

Mapping table

Database child call count

To convert the builtin:service.dbChildCallCount metric, use the dt.service.database.query.count Grail metric.

The following DQL query returns the number of database calls made by MY_SERVICE-00000—an equivalent of builtin:service.dbChildCallCount.

DQL query example

timeseries calls = sum(dt.service.database.query.count), interval:1m,
    by: { dt.smartscape.service, db.system, db.namespace },
    filter: { dt.smartscape.service == "<MY_SERVICE-00000>" }

Mapping table

Unsupported metrics

The following classic service metrics have no direct Grail equivalent. To approximate some of these metrics, you can use OpenPipeline to extract custom metrics from span data. For details, see Extract metrics from spans and distributed traces.

The Database section includes a DQL approximation using spans. For other categories, the classic metric keys are listed for reference—no DQL equivalent is currently available.

Database

The following DQL query returns the count and the duration of database spans for each database service, similarly to builtin:service.dbChildCallTime.

DQL query example

fetch spans, samplingRatio:1

// get only database client span
| filter span.kind == "client" and isNotNull(db.statement)

// calculate how frequently each span is sampled
| fieldsAdd sampling.probability = (power(2, 56) - coalesce(sampling.threshold, 0)) * power(2, -56)
| fieldsAdd sampling.multiplicity = 1/sampling.probability

// calculate the number of database spans after sampling
| fieldsAdd multiplicity = coalesce(sampling.multiplicity, 1)
                         * coalesce(aggregation.count, 1)
                         * dt.system.sampling_ratio

// calculate the duration of database spans after sampling
| fieldsAdd duration = coalesce(aggregation.duration_sum / aggregation.count, duration)

// aggregate records with the same values, by service ID
| summarize {
    operation_count_extrapolated = sum(multiplicity),
    operation_duration_avg_extrapolated = sum(duration * multiplicity) / sum(multiplicity)
}, by: { entityName(dt.entity.service), db.namespace }

CPU

Service method groups

Other