elastic / elastic/observability-migration-platform

Document Grafana dashboard export format requirements for file-based migration

Open Beginner friendly
#296 2 comments 0 reactions 0 assignees View on GitHub
asset:dashboards documentation good first issue program:operator-ux source:grafana workstream:stability
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.