Verifying Grafana Dashboard Restorations: Is Checksum or Manual Diff Sufficient?

Answer

Neither a per‑object checksum nor a manual visual diff is sufficient on its own to confirm that a Grafana backup has been restored correctly.

Why a checksum falls short

A checksum only proves that the restored JSON file is bit‑identical to the archived copy. It does not detect:

• Encrypted datasource secrets that fail to decrypt because the target instance uses a different secretKey.
• Semantic changes in alert rules caused by a different alerting engine or version‑specific expression syntax.
• Missing objects that were skipped during import (e.g., annotations) because the backup tool silently omitted them.

Why manual diff is inadequate

Manually comparing dashboards or rule lists does not scale, overlooks volatile fields (version, updated, IDs) that naturally differ, and cannot verify that datasources can actually query or that alert rules will evaluate.

Recommended verification workflow

1. After restore, record the source Grafana version and alerting engine (e.g., via GET /api/health and GET /api/frontend/settings).
2. For each object type (dashboard, datasource, alert rule, annotation) listed in the backup manifest:
   1. Fetch the object through the Grafana HTTP API using its UID or name.
   2. Normalize the JSON by stripping volatile fields: version, updated, created, id, any iteration timestamps, and auto‑assigned IDs.
   3. Compute a cryptographic hash (e.g., SHA‑256) of the normalized payload.
   4. Compare this hash to the one stored in the backup manifest; a match indicates bit‑identical content after normalization.
3. Validate datasources: call the datasource health‑check endpoint (POST /api/datasources/uid/{uid}/test) or run a simple query; a successful response confirms that the secret key matches and credentials are usable.
4. Validate alert rules: list restored rules (GET /api/rules) and, if possible, trigger a test notification through each rule’s contact point to confirm routing and evaluation work.
5. Finally, compare object counts by type between the source export and the target instance to catch any silent omissions.

One missing diagnostic detail

If you do not know whether the target Grafana instance uses the same encryption secretKey as the source, datasource credentials may appear present but fail to decrypt. Confirming key equality (or planning to re‑enter credentials) changes the recommendation: you must add a datasource‑credential test step.