Try one of my dashboards (single end-to-end migration)
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: take one dashboard the user already owns, migrate it all the way into Kibana, and set up a side-by-side so they can judge fidelity before committing to a bulk migration. This is the "prove it on something real" step — narrower than a full migration, higher-signal than inventory or a readiness verdict.
This skill writes exactly one dashboard to the target. It is otherwise read-only on the source.
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).
Step 1 — Scope to a single dashboard
How you pin to one dashboard differs by source. This is the most common place to get it wrong, so be explicit with the user about which path applies.
Datadog — by dashboard id (live API)
--dashboard-ids is Datadog only (help text: "Comma-separated Datadog dashboard IDs"). Pass exactly one id:
export DD_API_KEY="..." DD_APP_KEY="..." DD_SITE="datadoghq.com"
obs-migrate migrate \
--source datadog \
--input-mode api \
--dashboard-ids abc-def-123 \
--output-dir try_one_out \
--assets dashboards \
--field-profile otel \
--data-view "metrics-*"
(datadog-migrate --source api --dashboard-ids <id> also works; prefer unified obs-migrate migrate.)
Grafana — by single-dashboard export (no API id selector)
Grafana API mode has no --dashboard-ids selector. To migrate exactly one Grafana dashboard, point a files run at a directory that contains only that one dashboard's exported JSON:
# Put just the one dashboard export in its own directory first.
obs-migrate migrate \
--source grafana \
--input-mode files \
--input-dir ./one_dashboard \
--output-dir try_one_out \
--assets dashboards \
--data-view "metrics-*" \
--esql-index "metrics-*"
If the user only has live Grafana access, have them export the single dashboard's JSON (Grafana UI: Share → Export → Save to file, or the /api/dashboards/uid/<uid> endpoint) into an otherwise empty directory, then run the files command above. Do not pretend an API id selector exists for Grafana.
Use --assets dashboards here — a single-dashboard trial is about the dashboard. (Alerts are a separate Phase D skill.) For Prometheus fidelity, set --esql-index to the metrics data stream even when --data-view differs as the Kibana UI bind (see https://github.com/elastic/observability-migration-platform/blob/main/docs/command-contract.md → Target index flags).
Step 2 — Add the target and upload
For a real side-by-side you want the dashboard in Kibana, ideally validated against live data. Add the target endpoints you have, then upload.
export ELASTICSEARCH_ENDPOINT="https://...es..." KIBANA_ENDPOINT="https://...kbn..." KEY="<api-key>"
# Re-run Step 1 with live target discovery / query validation:
# ...append: --es-url "$ELASTICSEARCH_ENDPOINT" --es-api-key "$KEY"
# (Grafana uses native PromQL by default; with --es-url it verifies target
# support and downgrades to ES|QL translation if unsupported)
# Review native artifacts, then upload via the typed Dashboards API:
# try_one_out/dashboards/native/*.native.json
obs-migrate upload \
--artifact-dir try_one_out/dashboards \
--kibana-url "$KIBANA_ENDPOINT" \
--kibana-api-key "$KEY"
Optional one-shot: append --upload --kibana-url … --kibana-api-key … to the Step 1 migrate command instead of a separate upload (same typed Dashboards API path). Prefer the two-step flow when the user wants to review native/*.native.json first.
uploadreads the persisted native payloads undernative/and sends them byte-for-byte through the typed Dashboards API — that is the only input it accepts. Reviewnative/*.native.json(andir/*.ir.json) before uploading.- Adding
--es-urlduring Step 1 turns on live target field discovery and emitted-query validation; without it the run stays in offline analysis and panels may look empty for lack of data, not because the translation is wrong. - Custom-CA / self-signed clusters: all CLIs accept
--ca-cert <path>(envOBS_MIGRATE_CA_CERT) to verify against a private CA, or--insecure(envOBS_MIGRATE_INSECURE) to skip verification for testing only. These apply to source, Elasticsearch, and Kibana (including the dashboard upload).
Step 3 — Do the side-by-side
- Read the verdict first:
try_one_out/dashboards/migration_summary.md— human-readable verdict, scorecard, per-panel table, and must-fix worklist for the one dashboard. - Drill per panel:
try_one_out/dashboards/migration_manifest.json→panels[].status,panels[].grafana_type(Datadog:datadog_widget_type),panels[].reasons, andpanels[].verification_packet.semantic_gate. Expectmigrated_with_warningsfor accepted approximations (e.g.histogram_quantile→PERCENTILE); hand those toexplain-migration-gapsrather than treating them as hard failures. - Open both dashboards: the original in Grafana/Datadog and the uploaded one in Kibana, panel by panel. Compare numbers, series count, and shape.
- Optional stronger gates:
obs-migrate compare/validate-side-by-sidefor numeric parity;--smokeon migrate orgrafana-validate-uploadedfor saved-object checks; render audit (https://github.com/elastic/observability-migration-platform/blob/main/docs/testing.md) for Lens render truth. - For any panel that looks wrong or empty in Kibana, hand off to the
debug-uploaded-kibana-dashboardskill — it captures the exact ES|QL Kibana is running and classifies the failure (render_errorvsfield_gap/data_gap).
Honest limits (tell the user)
- Grafana single-dashboard = a one-file export. There is no Grafana API id selector; scope by
--input-dircontaining only that dashboard.--dashboard-idsis Datadog-only. - Empty panels are often missing data, not a bug. A clean translation can still render empty if the target cluster has no matching telemetry. Use
prepare-target-telemetryand/orobs-migrate seed-sample-data --artifact-dir try_one_out/dashboards(tear down withobs-migrate remove-sample-data --confirm); say so rather than blaming the translator. Lab seeding is optional investigation — not required for the product path when real target telemetry exists. - No
--es-url⇒ no live validation. Treat an offline run as directional; it does not prove panels render against real data. - Degrade gracefully: unsupported panels are surfaced as
requires_manual/not_feasiblewith reasons; many others land asmigrated_with_warningsfor documented approximations — relay those, never hide them.
Do NOT
- Do not invent a Grafana API
--dashboard-idsflag — it does not exist for Grafana; use a single-dashboard files export. - Do not claim panels are validated when the run had no
--es-urland no upload smoke / render check. - Do not bulk-migrate here. Selecting many dashboards (by folder/tag/datasource/team) or migrating everything is the Phase D "migrate selected / every supported dashboard" skill.
- Do not cite manifest fields you have not confirmed (e.g.
grafana_typeexists on Grafana manifest panels; open the JSON when unsure). - Do not assume a repo checkout or eng-only harness paths.
See also
install-obs-migrate— install/doctor when the CLI is missing or not Ready.scan-o11y-environmentskill — inventory of what exists (pick the dashboard to try from here).assess-migration-readinessskill — feasibility verdict and evidence level before trying.prepare-target-telemetryskill — field profile / seed path so panels are not empty.explain-migration-gapsskill — plain-language warnings vs hard stops.debug-uploaded-kibana-dashboardskill — diagnose a single broken uploaded panel.revert-migrationskill — remove generated assets; orobs-migrate cluster delete-dashboards --dashboard-ids <id>for the one uploaded dashboard.obs-migrate upload --help,obs-migrate migrate --help— confirm flags for the installed version.https://github.com/elastic/observability-migration-platform/blob/main/docs/command-contract.md— upload, cluster, and live-extraction flags and artifacts (online docs / repo).