Assess migration readiness
Audience: operators of the published obs-migrate CLI (PyPI/uvx), using public docs and their real source + Elastic/Kibana — not a repo lab harness.
Goal: give the user a realistic, trust-qualified verdict of what migrates cleanly vs. what needs rework — without over-promising. The single most important thing to communicate is how much evidence the verdict is based on.
Lead with evidence level (do not skip this)
For Grafana, the preflight report stamps an evidence_level that tells the user how much to trust the verdict:
evidence_level |
Means | Confidence |
|---|---|---|
full |
target ES and source (Prometheus/Loki) were reachable | highest |
target_only |
only --es-url was provided |
medium |
source_only |
only source URLs were provided | medium |
static_analysis |
neither — translation analysis only | directional only |
Always tell the user which level their run achieved. A clean-looking verdict at static_analysis is not a guarantee the queries run against real data.
Datadog: --preflight runs a different checker (issues embed in migration_report.json). It does not emit Grafana's preflight_report.json / evidence_level contract. Treat Datadog preflight as gap surfacing (block/warn/info), and use target validation + try-one/validate-side-by-side for confidence — do not invent an evidence_level for Datadog.
Prerequisites (install)
These skills help operators of the published CLI (not a repo checkout).
If obs-migrate is missing or doctor is not Ready, follow
install-obs-migrate first — that skill owns PyPI/uvx/pip, extras, and
Python/uv gotchas. Do not invent alternate install commands here.
uvx --from 'elastic-observability-migration[all]' obs-migrate doctor
# After a persistent install, the same check is: obs-migrate doctor
Source/Elastic credentials: connect-to-o11y-source (and your env exports).
Run the assessment
Readiness comes from a preflight run (--preflight): it translates and analyzes, optionally validates against live systems, and writes a customer-facing readiness report. It does not upload.
Prefer the unified CLI for target-aware Grafana preflight. --prometheus-url / --loki-url exist on grafana-migrate only (not on obs-migrate migrate) — use the dedicated CLI when you need evidence_level: full:
export GRAFANA_URL="https://grafana.example.com" GRAFANA_USER="..." GRAFANA_PASS="..."
export ELASTICSEARCH_ENDPOINT="https://...es..." KEY="<api-key>"
# Canonical package entry (target-aware preflight):
obs-migrate migrate \
--source grafana --input-mode api \
--output-dir readiness_out \
--assets all \
--preflight \
--field-profile otel \
--data-view "metrics-*" \
--esql-index "metrics-*" \
--es-url "$ELASTICSEARCH_ENDPOINT" \
--es-api-key "$KEY"
# Highest evidence (also validate against live Prometheus/Loki) — dedicated CLI:
grafana-migrate \
--source api \
--output-dir readiness_out \
--assets all \
--preflight \
--data-view "metrics-*" \
--esql-index "metrics-*" \
--es-url "$ELASTICSEARCH_ENDPOINT" \
--es-api-key "$KEY" \
--prometheus-url "https://prometheus.example.com" \
--loki-url "https://loki.example.com"
--prometheus-url/--loki-urltake literal URLs — there are no standard$PROMETHEUS_URL/$LOKI_URLrepo env vars; substitute the user's real endpoints or omit them.- Populated targets: Grafana may use
--field-profile auto --es-url ...when telemetry already exists (ambiguous caps →otel+ warn); otherwise choose an explicit planned profile (prepare-target-telemetry). Datadog always requires an explicit profile — noauto. - Set
--esql-indexfor Prometheus query/discovery even when--data-viewdiffers as the Kibana UI bind. - Drop
--es-url/source URLs to run a fasterstatic_analysispass (state the lower confidence).
Where to read the verdict (Grafana)
Primary artifact: readiness_out/dashboards/preflight_report.json.
| What | Field |
|---|---|
| Overall evidence/trust | evidence_level |
| Clean vs. rework buckets | summary.readiness: ready (clean) · needs_metrics_mapping / needs_log_fielding (mapping rework) · manual_only (redesign) |
| Quality gates | summary.semantic_gates: green / yellow / red |
| Hard stops | blockers (Red-gated panels, missing required fields, non-migratable datasources, unresolved datasource template variables, RED cluster health, missing metrics) |
| Prep work (not blocking) | actions (field mapping needed, unconfirmed counters, missing labels, high-complexity dashboards, YELLOW cluster). Grafana profile_mismatch on required_target_contract.json is operator visibility — check planned vs detected layout there; it is not a separate preflight blocker. |
| One-paragraph readout | customer_action_summary |
Human-readable: readiness_out/dashboards/migration_summary.md (verdict, scorecard, must-fix worklist).
Per-panel drill-down: readiness_out/dashboards/migration_manifest.json → panels[].readiness, panels[].status, panels[].verification_packet.semantic_gate, panels[].reasons. Expect migrated_with_warnings for accepted approximations — triage with explain-migration-gaps, not as automatic blockers.
How to judge confidence (tell the user)
High confidence (Grafana) requires all of: evidence_level: full, blockers empty, Green dominating semantic gates. Treat static_analysis as directional — a files-mode run without --es-url (or with --es-url "") never executes ES|QL, so a 100% green score there is not live proof. Yellow/Red gates, metrics_missing, datasource_audit.non_migratable_panels, or datasource_audit.unresolved_datasource_variables represent real manual effort — the tool surfaces these gaps rather than hiding them (degrade-gracefully). non_migratable: [] is not a clean bill when unresolved template-variable datasources remain. Preflight does not prove Lens UI render; for that, use render audit / validate-side-by-side after a try-one upload (https://github.com/elastic/observability-migration-platform/blob/main/docs/testing.md).
Do NOT
- Do not report a Grafana readiness verdict without stating its
evidence_level. - Do not invent Grafana
evidence_level/preflight_report.jsonsemantics for Datadog. - Do not imply
$PROMETHEUS_URL/$LOKI_URL(or other) env vars exist for the source-validation flags; pass literal URLs. - Do not present
static_analysisresults as a guarantee panels will render against live data. - Do not treat
datasource_audit.non_migratable: []as a clean datasource bill — also readunresolved_datasource_variables. A panel whose datasource is$datasourcerather than a literal type can hide InfluxDB/SQL until that list is empty. A concretedatasource.typewith a${DS_*}uid (Grafana marketplace export) is not unresolved. - Do not restate inventory counts as "readiness" — that is
scan-o11y-environment. - Do not claim
obs-migrate migrateaccepts--prometheus-url/--loki-url— usegrafana-migratefor those.
See also
install-obs-migrate— install/doctor when the CLI is missing or not Ready.scan-o11y-environmentskill — the descriptive inventory layer beneath this.prepare-target-telemetryskill — field profile /--esql-indexbefore readiness claims.explain-migration-gapsskill — warned vs blocked panel triage.prepare-production-cutoverskill — final go/no-go after validation gates.obs-migrate migrate --help/grafana-migrate --help— confirm--preflight,--es-url,--prometheus-url,--loki-urlfor the installed version.https://github.com/elastic/observability-migration-platform/blob/main/docs/command-contract.md— preflight/validation flags and artifacts (online docs / repo).https://github.com/elastic/observability-migration-platform/blob/main/docs/testing.md— layered verifier / render-audit gates beyond preflight.