lgtm-migrate User Guide

Everything you need to convert Datadog dashboards and monitors to Grafana.

What lgtm-migrate does

lgtm-migrate is a command-line tool that converts Datadog dashboard and monitor JSON exports into Grafana dashboards and Grafana-managed alert rules — metric queries become PromQL, log queries become LogQL. Anything that can't be automatically mapped ships as a clearly-labeled TODO placeholder rather than being silently dropped, so nothing goes missing without you knowing about it.

Installing

Grab the binary for your platform from the link in your confirmation email, or from the pricing section. Unzip it and put it somewhere on your PATH (e.g. /usr/local/bin).

Confirm it's installed:

lgtm-migrate --help

Free tier vs. a paid license

Without a license, lgtm-migrate runs on the free tier: 10 dashboard conversions and 10 alert rule conversions, total. A paid license removes the limit entirely; see Activating a license.

Signing up for the free tier (required before your first conversion)

You'll need to sign up before running convert or convert-alerts for the first time. Run: 

lgtm-migrate signup

This opens the signup page — enter your email there and you'll get a confirmation link. Click it, click the confirm button on the page that opens, then activate the token it shows you — this only needs to happen once per machine: 

lgtm-migrate --free-tier-token <token> license status

After that, every convert/convert-alerts run picks up the saved token automatically — you don't need to pass it again.

Converting your first dashboard

Export a dashboard from Datadog as JSON, then:

lgtm-migrate convert dashboard.json

This writes dashboard_grafana.json next to the input by default. Import that file into Grafana (Dashboards → New → Import), or use -o to control where it's written: 

lgtm-migrate convert dashboard.json -o out.json
lgtm-migrate convert dashboard.json -o -   # print to stdout instead of a file
lgtm-migrate convert *.json                # convert a whole directory at once

Each conversion prints a one-line summary — panels found, targets found, how many converted, and how many became TODO placeholders — so you can see conversion quality at a glance before opening Grafana.

AI-assisted TODO fixing (optional)

If a query can't be automatically mapped, add --ai to have an LLM attempt a fix instead of leaving a TODO placeholder. It auto-detects a provider from your environment (Anthropic, OpenAI, or Gemini API keys), or you can be explicit: 

lgtm-migrate convert dashboard.json --ai --ai-provider anthropic --ai-key sk-...

Converting alert rules / monitors

Export a monitor from Datadog as JSON, then:

lgtm-migrate convert-alerts monitor.json

The output is Grafana's alert-rule provisioning JSON. --mimir-uid/--loki-uid should match the datasource UIDs configured in your own Grafana instance (defaults: mimir and loki), since alert rules reference a fixed datasource rather than a template variable the way dashboards do: 

lgtm-migrate convert-alerts monitor.json \
  --mimir-uid your-mimir-uid \
  --loki-uid  your-loki-uid \
  --folder-uid your-target-folder

Activating a paid license

Your purchase confirmation email contains a license key. Activate it once on each machine you use — it's saved for future runs, so you don't need to pass it again: 

lgtm-migrate --license <key> license status

From then on, every convert/convert-alerts run is unlimited — no need to keep passing --license. Check what's active anytime with: 

lgtm-migrate license status

This also shows your included email-support window, which starts at purchase and runs for 30 days (Starter), 90 days (Professional), or 12 months (Enterprise) — your license to convert unlimited assets itself never expires.

Validating against your own Grafana instance (optional)

If you've already pushed dashboards/alert rules into Grafana and want to check that every query actually runs (rather than just that the conversion succeeded), audit/audit-alerts run each query against your Grafana + Mimir/Loki and report errors or no-data: 

lgtm-migrate audit        --grafana https://your-grafana --mimir https://your-mimir/prometheus
lgtm-migrate audit-alerts --grafana https://your-grafana --mimir https://your-mimir/prometheus --errors-only

Troubleshooting

A lot of my alert rules are TODO placeholders

This is expected for monitors using proprietary SaaS metrics with no Prometheus equivalent (ML-based Datadog functions like anomalies()/forecast() also can't be mapped). TODO rules are inert — they never fire — rather than being dropped or silently converted into something wrong. Try --ai on a re-run; it resolves a meaningful share of these automatically.

"free tier requires signing up first"

Expected on a fresh install — free-tier usage has to be tied to your account before your first conversion. See Signing up for the free tier above.

"free tier is limited to 10 ... files total" but I haven't converted that many recently

The cap is lifetime, not per-run. Check lgtm-migrate license status to see what's currently active, or purchase a license to remove the limit.

My license key doesn't activate

Double check you copied the whole key, including everything after the . — it's two base64url segments joined by a period, and a truncated copy/paste is the most common cause of an "invalid license key" error. If it still doesn't work, email us (below) with the email address you purchased under and we'll reissue it.

Getting support

Paid licenses include email support for the window shown by lgtm-migrate license status. Reach us at info@shiftmetrics.com — include your license email and, if it's a conversion issue, the specific dashboard/monitor JSON that isn't converting the way you expect.