Your classic SLOs have been running for years, but their metric expressions are getting hard to maintain and the team wants to drive everything with DQL. You cannot migrate SLOs to Grail in one click: each objective has to be rewritten, compared and then switched over without losing track of the error budget. This tutorial shows how to migrate SLOs to Grail one at a time, without breaking your alerts.
Goal: by the end you will have an inventory of your classic SLOs, their DQL equivalent on Grail, a side-by-side run proving that both calculations agree, and a plan to switch your alerts. This applies to Dynatrace SaaS: the new SLOs rely on Grail, which does not exist on Dynatrace Managed. On Managed you stay on classic SLOs; the dedicated section below explains what to prepare.
If you are starting from scratch with indicators, first read how to choose your SLIs with DQL.
The problem: two SLO engines that drift apart
A classic SLO computes its ratio from a metric expression (for example builtin:service.errors.total.successCount divided by builtin:service.requestCount.total). An SLO on Grail computes its ratio from a DQL query. The two engines do not necessarily aggregate the same way: resolution, handling of data gaps, entity scope. Without a comparison, you risk switching to an SLO that shows 99.95% where the old one showed 99.80%, hiding real budget consumption.
Prerequisites
- A Dynatrace SaaS environment on the Grail platform, with the Service-Level Objectives app (the exact name may vary by version: check docs.dynatrace.com).
- A classic API token with the SLO read scope (
slo.read) for the inventory. - Permissions to read metrics in Grail and to create SLOs in the new app.
curlandjqon your workstation.
Step 1: inventory the classic SLOs
The classic SLO API v2 returns the paginated list, with the target, the timeframe and the metric expression.
export DT_ENV="https://YOUR-ENV.live.dynatrace.com"
export DT_TOKEN="dt0c01.XXXX" # scope slo.read
curl -s "$DT_ENV/api/v2/slo?pageSize=200&evaluate=false" \
-H "Authorization: Api-Token $DT_TOKEN" \
| jq -r '.slo[] | [.id, .name, .target, .timeframe, .metricExpression] | @tsv' \
> slo-inventory.tsv
wc -l slo-inventory.tsv
The critical fields: target (the target, for example 99.9), timeframe (for example -30d) and metricExpression, the formula to translate. If the response contains a nextPageKey, call again with that parameter.
Step 2: triage before migrating
Do not migrate everything. Put each inventory line into one of three groups:
- Migrate: an SLO that is tracked, linked to an alert or a dashboard.
- Merge: several SLOs measuring the same journey with slightly different filters.
- Delete: an orphan SLO nobody looks at. Every SLO you keep costs maintenance: that is toil.
Step 3: migrate SLOs to Grail by rewriting the SLI in DQL
Take a classic success-rate SLO for a service. On Grail, service metrics are exposed under keys such as dt.service.request.count and dt.service.request.failure_count. The following query computes the SLI over the same period:
timeseries {
total = sum(dt.service.request.count),
failures = sum(dt.service.request.failure_count)
},
by: { dt.entity.service },
filter: { in(dt.entity.service, "SERVICE-0123456789ABCDEF") }
| fieldsAdd sli = 100 * (total[] - failures[]) / total[]
Points to watch:
total[] - failures[]applies the operation to each interval of the series: the SLI is therefore a time series, which is what a custom SLO expects.- The output field name matters. Custom SLO templates expect a specific field (often
sli): check the convention in the app documentation before saving. - Replace the hard-coded service ID with a filter on a tag or zone as soon as several services are involved.
Then create the SLO in the app: paste the query and reuse exactly the same target and timeframe as the classic SLO. Changing the target during the migration would make the comparison useless.
Step 4: the side-by-side run
Keep both SLOs active for at least one full window, ideally two. Compare the values every day. On the classic side, the API returns the evaluation:
curl -s "$DT_ENV/api/v2/slo/SLO_ID?timeFrame=CURRENT" \
-H "Authorization: Api-Token $DT_TOKEN" \
| jq '{name, evaluatedPercentage, errorBudget}'
On the Grail side, reuse the query from step 3 and aggregate over the full window:
timeseries {
total = sum(dt.service.request.count),
failures = sum(dt.service.request.failure_count)
},
from: now()-30d,
filter: { in(dt.entity.service, "SERVICE-0123456789ABCDEF") }
| fieldsAdd t = arraySum(total), f = arraySum(failures)
| fieldsAdd sli = 100 * (t - f) / t
| fields sli
Accept a small gap (a few hundredths of a point) caused by aggregation differences. A larger gap almost always means a different scope: an added service, a forgotten key-request filter, or synthetic requests counted on one side and not the other.
Step 5: switch the alerts
The migration is only finished when on-call is alerted by the new SLO. Reuse the multi-window logic described in SLO burn rate alerts in Dynatrace, applied to the Grail SLO. Enable the new alert, keep the old one running in parallel for a few days, then disable the old one. Only delete the classic SLO after exporting its history if your monthly reports depend on it.
If you manage SLOs as code, update your Terraform definitions instead of clicking in the UI: see Dynatrace SLOs with Terraform. Check in the provider documentation which resource maps to the new SLOs, as it differs from the classic SLO resource.
What about Dynatrace Managed?
Dynatrace Managed has no Grail: the new SLOs are not available there. You can still prepare a future move to SaaS:
- export the inventory with the same API call (the URL then contains
/e/ENVIRONMENT-ID); - clean up orphan SLOs right now;
- document, for each SLO, its business intent in one sentence. It will survive the rewrite.
How to check that it works
- In the SLO app, the new SLO shows a status and a remaining error budget, with no query error.
- The side-by-side comparison table shows a small, stable gap across the whole window.
- In a Notebook, the step 4 query returns a single row with an
sliconsistent with the app. - A controlled test (errors injected in pre-production) lowers both SLOs in the same way and fires the new alert.
Best practices
- Keep the target unchanged during the migration: change the engine or the target, never both at once.
- Migrate in batches: start with the three most-watched SLOs, not all fifty.
- Name things clearly: a temporary suffix such as “(Grail)” avoids mixing up the two SLOs during the side-by-side run.
- Record decisions: log every merge or deletion in a ticket, with the reason.
- Review dashboards: tiles pointing to the old SLO must follow, see the SLO dashboard for leadership.
Frequently asked questions
Is there an automatic migration tool for classic SLOs?
Capabilities change between Dynatrace SaaS versions. Check the official documentation to see whether a conversion assistant is offered in your environment. Even with an assistant, the side-by-side run remains essential to validate the numbers.
Do you lose the error budget history when migrating?
The new SLO recomputes its SLI from the data held in Grail, according to your metric retention. The classic SLO history is not transferred as is. Export it if you need it for reports.
Can classic SLOs and Grail SLOs coexist?
Yes, and during the transition it is even recommended. In the long run, avoid two sources of truth for the same objective: on-call must know which number counts.
Conclusion
To migrate SLOs to Grail, first triage, then rewrite each SLI in DQL, compare over a full window and only then switch the alerts. This discipline stops you “gaining” reliability points just by changing the calculation, and keeps the error budget honest.
span.observer is an independent community blog, not affiliated with Dynatrace LLC. Dynatrace is a trademark of its owner. SaaS features evolve quickly: check their availability in your environment and in the official documentation.