elastic / elastic/observability-migration-platform
Document Grafana dashboard export format requirements for file-based migration
- Dominant language
- Python
- Stars
- 6
- Forks
- 8
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 23
Description
## Summary
`--input-mode files` dashboard migration only understands one shape of Grafana dashboard export, but the Grafana UI's Export dialog offers several. Nothing in our docs tells operators which one to pick, so it's easy to export the wrong thing and get a confusing failure with no obvious cause.
## Current behavior (verified)
- `extract_dashboards_from_files()` only globs `*.json` and only recognizes a document with a top-level `panels`/`rows` key (or the `{"dashboard": {...}}` API wrapper).
- Grafana's newer **V1 resource** and **V2 resource** export models wrap the dashboard body under `apiVersion`/`kind`/`metadata`/`spec` instead. The extractor doesn't unwrap `spec`, so these exports — JSON or YAML — are silently skipped, surfacing only as `no Grafana dashboards found ... expected top-level 'panels' or 'rows' key`.
- The default export (no need to open Advanced options) already produces the working shape: **Classic model, JSON format**.
- The "Share dashboard with another instance" / "Export for sharing externally" toggles were verified to have no effect on migration output (tested by exporting the same dashboard both ways and diffing the result) — they only swap datasource `uid`/`name` for a placeholder in report metadata.
## Proposal
- [ ] Add a short "File Export Scope" note to `docs/sources/grafana.md`, alongside the existing "Live Extraction Scope" section, stating: use the default export (Model = Classic), no need to open Advanced options; V1/V2 resource and YAML aren't supported; the sharing toggles don't matter.
## Non-goals
- Adding support for V1/V2 resource unwrapping or YAML ingestion (separate follow-up if desired).
## Related
- `observability_migration/adapters/source/grafana/extract.py` (`extract_dashboards_from_files`)
- `docs/sources/grafana.md` § Live Extraction Scope
Contributor guide
Research direction
Open docs/sources/grafana.md and read the existing "Live Extraction Scope" section. Add the proposed "File Export Scope" note describing the default Classic JSON export, unsupported V1/V2 resource and YAML exports, and the sharing-toggle behavior. Done means the documented guidance matches the verified file-based migration behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- grafana, python
- Domain
- documentation, observability-sre
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 85/100