From 7ef59a9091b2d9994a631e7104f0f9c49624da02 Mon Sep 17 00:00:00 2001 From: Lucy Murray Date: Tue, 30 Jun 2026 15:45:00 +0200 Subject: [PATCH 1/2] docs: add "Run your first migration" section to README Closes #255 --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index c89bb5ff..97c6e30f 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,47 @@ entry point. For full command walkthroughs, env-file setup, and end-to-end flows, see [`docs/command-contract.md`](docs/command-contract.md). +## Run your first migration + +Once `obs-migrate doctor` reports a healthy environment, you can migrate a +dashboard with no Elastic or Kibana credentials. The repo ships sample +dashboards for exactly this, so list them first (offline, no setup): + +```bash +.venv/bin/obs-migrate list-samples +``` + +Then migrate the bundled Grafana sample from files into a local output +directory: + +```bash +.venv/bin/obs-migrate migrate \ + --source grafana \ + --input-mode files \ + --input-dir observability_migration/sample_dashboards/grafana/prom-basics \ + --output-dir sample_out +``` + +This translates the dashboard into Kibana-ready YAML. Anything that can't be +expressed natively, such as the sample's World Map panel, is kept as a +manual-review marker rather than silently dropped. + +Everything is written under your `--output-dir`: + +- `sample_out/dashboards/yaml/`: the generated dashboard YAML +- `sample_out/dashboards/compiled/`: the compiled Kibana NDJSON +- `sample_out/dashboards/migration_summary.md`: a human-readable verdict, + scorecard, and per-dashboard worklist; read this first + +To go further: + +- [`docs/command-contract.md`](docs/command-contract.md): the full command + reference (env-file setup, live API extraction, alerts, and upload). Reach + for it as the reference once the example above works, not as the starting + point. +- [`docs/known-limitations.md`](docs/known-limitations.md): what the tool + can't translate yet. + ## Compatibility - **Python**: 3.11+ From d70f65b61cb66c42e0d07f0f92c8f0aac53c47bb Mon Sep 17 00:00:00 2001 From: Lucy Murray Date: Mon, 3 Aug 2026 09:59:40 +0200 Subject: [PATCH 2/2] docs: remove known-limitations.md link (file being removed in #328) --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 97c6e30f..282f7e0c 100644 --- a/README.md +++ b/README.md @@ -96,8 +96,6 @@ To go further: reference (env-file setup, live API extraction, alerts, and upload). Reach for it as the reference once the example above works, not as the starting point. -- [`docs/known-limitations.md`](docs/known-limitations.md): what the tool - can't translate yet. ## Compatibility @@ -113,7 +111,6 @@ To go further: - Docs index — [`docs/README.md`](docs/README.md) - Canonical commands — [`docs/command-contract.md`](docs/command-contract.md) -- Known limitations — [`docs/known-limitations.md`](docs/known-limitations.md) - Architecture — [`docs/architecture.md`](docs/architecture.md) - Grafana source — [`docs/sources/grafana.md`](docs/sources/grafana.md) - Datadog source — [`docs/sources/datadog.md`](docs/sources/datadog.md)