Migrate from Grafana
Preview Feature
Cribl is still developing this Preview feature. We don’t recommend using it in a production environment, because the feature might not be fully tested or optimized for performance, and related documentation could be incomplete.
Please continue to submit feedback through normal Cribl support channels, but assistance might be limited while the feature remains in Preview.
Assess and import supported Grafana Dashboards and alert rules into Cribl Search, without rebuilding them by hand.
About Grafana Migration
A migration connects to Grafana, inventories your Grafana Dashboards, alert rules, and their dependencies, and classifies every selected resource before it creates anything in Cribl Search. You review the compatibility results, approve an import plan, and then import what is ready.
Each migration covers one resource type. A migration that you start from the Dashboards page migrates Dashboards, and a migration that you start from the Monitors page migrates alert rules. See Start a Migration.
This workflow is separate from the two other ways Cribl Search works with Grafana:
- Query metrics from Grafana through the Prometheus-compatible endpoint on a
metricsDataset. - Visualize Cribl Search Results in Grafana by running Cribl Search queries through the Cribl Search plugin.
What Migrates
A migration imports Grafana Dashboard definitions, not the metrics they chart. Those metrics must already be present in
a metrics Dataset. See Before You Begin.
For each Prometheus-backed Dashboard you select, Cribl Search converts it into a Dashboard in a Collection you choose. The conversion includes supported Grafana layouts, rows, panels, variables, and code-mode Prometheus Query Language (PromQL).
| Grafana resource | What Cribl Search does |
|---|---|
| Prometheus or Mimir Dashboards | Imports supported content as Dashboards. |
| Alert rules | Imports simple threshold rules as paused Monitors, with their Notification routing. Assesses the rest, so you know what to rebuild. |
| Contact points and Notification policies | Maps each contact point to a Cribl Notification target, then recreates the routing on each Monitor or as Notification policies. |
| Loki, Tempo, SQL, InfluxQL, Elasticsearch, and other non-Prometheus Dashboards | Doesn’t migrate. |
| Silences, message templates, and alert history | Doesn’t migrate. Cribl Search uses the default template for each Notification target type. |
Anything Cribl Search can’t reproduce is reported during review rather than dropped. Examples include an unsupported panel type, a Grafana Macro, or an expression. Imported PromQL stays verbatim in Code mode, so a Dashboard that would silently lose behavior is never classified as Ready.
A migration is a one-time import, not a continuous sync. Start another migration to pick up later Grafana changes.
Before You Begin
You’ll need:
- A
metricsDataset that holds the metrics your Grafana Dashboards query. Only Prometheus-backed and Mimir-backed Dashboards migrate, and assessment classifies queries against this Dataset. If the metrics are not in Cribl Search yet, ingest them first. See Ingest Prometheus Metrics into Cribl Search. - Permission to create and update Dashboards and Monitors in Cribl Search, and to create migration runs.
- A Grafana account that can read the folders, Dashboards, data sources, and alert rules you want to migrate. To migrate Notification routing, the account must also read contact points, Notification policies, and mute timings.
- A Grafana service account token, stored as a Global Secret.
- One or more Notification targets in Cribl Search that match your Grafana contact points, if you want to migrate Notification routing. You can also create targets during the migration. See Map Contact Points to Notification Targets.
To read a resource’s raw Grafana export during review, you need a separate Permission to read source snapshots. If you have read-only access, you can see migration runs and non-secret connection details, but you can’t create runs, change connections, or import.
Creating a Notification target from the Map step, and importing Notification policies, each require their own write access to Notification targets and Notification policies. Migration Permission doesn’t cover them. See Permissions.
Imported Monitors notify no one unless Notifications are turned on for your deployment. Review warns you when they aren’t. See Review Compatibility.
For a live connection, Cribl Search must be able to reach your Grafana URL over HTTPS with a valid TLS certificate.
Cribl Search doesn’t tunnel into a private network, so if Grafana isn’t reachable, upload a .json export instead.
Requests to private, loopback, link-local, and cloud metadata addresses are rejected.
Start a Migration
Open the page for the resource type that you want to migrate:
- To migrate Dashboards, select Dashboards from the Cribl Search sidebar.
- To migrate alert rules as Monitors, open the Monitors page.
Select Migrate.
The Migrate button appears only when the migration feature is turned on for your deployment.
Select New Migration.
On a Dashboards migration, under Choose a source path, select one of the following:
- Connect to Grafana to discover content over a live connection.
- Upload dashboard JSON when Cribl Search can’t reach Grafana.
A migration covers only the resource type of the page where you started it, so start one migration from each page to
migrate both. An alert rules migration always connects to Grafana, because Cribl Search can’t read alert rules from a
.json export.
A .json export doesn’t carry every resource a Dashboard depends on, so an upload run can leave folders, data sources,
or library panels unresolved. Assessment reports those unresolved dependencies.
Each migration is a run that you can leave and return to. To resume, select the run in the Migrations list, then select Resume at the current stage, for example Resume at Connect. Completed runs offer Open.
Connect to Grafana
- Under Grafana connection, select one of the following:
- Select an existing connection.
- Create a connection and enter your Grafana URL.
- Under Secret, select the secret that holds your Grafana service account token.
- Select Test Connection.
- When the test reports Connection test passed., review the detected Grafana version and capabilities.
- Select Start Discovery.
Cribl Search stores only a reference to the Global Secret. It never returns the token to the browser, includes it in reports, or prefills it in the form. A connection that already has a credential shows Credential configured. If you can manage connections, select Replace credential to point the connection at a different secret.
You can’t continue past a connection that hasn’t been tested, or one whose test failed. A failed test names one of these causes:
| Reported cause | What to do |
|---|---|
| The source is unreachable | Check the URL, DNS, TLS certificate, and network path. |
| Credentials were rejected | Confirm that the token is valid and hasn’t expired, then replace the credential. |
| Permissions are missing | Grant the service account read access to the resources you want to migrate. |
| The version is unsupported | Upgrade Grafana, or use the upload path. |
| A required API is missing | Confirm that the Grafana instance exposes the Dashboard and folder APIs. |
| The request was blocked | The destination is disallowed by egress policy. Use a reachable public URL, or upload a .json export. |
| Connection testing is unavailable | Connection testing isn’t enabled on the node serving the request. Contact Cribl Support. |
Discover and Select Resources
Discovery inventories what your connection can read, and shows its progress by resource type. It resumes where it left off if you navigate away, and you can cancel it at any time.
Discovery also inventories your contact points, Notification policies, and mute timings, and lists each in its progress by resource type. If your Grafana version doesn’t expose one of these resource types, discovery reports that type as absent and still completes every other type.
If Grafana denies access to some resources, discovery shows a partial-permission warning rather than reporting a complete inventory. Grant the missing Grafana permissions and run discovery again if you expect those resources.
Cribl Search keeps only a non-secret summary of each contact point, such as its integration type and whether it holds credentials. Grafana redacts the credentials themselves, and Cribl Search never stores them.
When discovery finishes, choose what to migrate. A Dashboards migration shows Select Dashboards, and an alert rules migration shows Select Alert Rules:
- Use Search folders and dashboards to filter the tree.
- Under Select Dashboards, expand a folder in Dashboards by folder to see its Dashboards, each with a panel and data source count.
- Select the Dashboards you want. Selecting a folder selects everything in it, and a partly selected folder shows an indeterminate check box.
- Under Select Alert Rules, select the rules you want to assess.
- Expand Dependency summary for selection to see what your selection references, including anything unresolved.
- Select Continue to Mapping.
A resource you clear never appears in the assessment, the import plan, or the results.
Map Data Sources and Folders
Under Map Data Sources & Folders:
- Map each supported Prometheus or Mimir data source to the
metricsDataset that holds its metrics. - Set the Default Dataset, which Cribl Search uses for queries whose data source is unmapped or absent.
- Map each Grafana folder to an existing Collection, or type a name to create one.
- Map each Grafana contact point to a Notification target. See Map Contact Points to Notification Targets.
- Select Run Assessment.
Assessment can take a while, because it validates the queries in every selected Dashboard against your metrics. While assessment is in progress, the page stays on screen and the button reads Assessing…, or Retrying… with an attempt count. Select Cancel assessment to stop the pass and return to editable mapping. You can reload the page or come back later without losing progress.
If a pass fails, the page reports Assessment failed and keeps your mapping. The two common causes are missing Dataset-read Permission, and repeated internal failures. Fix the cause, then select Re-run Assessment.
Map Contact Points to Notification Targets
Under Contact Points → Notification Targets, each Grafana contact point maps to one Cribl Notification target. Cribl Search uses the mapping to route the alerts of each imported Monitor to where Grafana sent them. For each row:
- Under Notification Target, select an existing target, or select Add Target to create one.
- Repeat for each contact point that your selected alert rules use.
Cribl Search lists only the targets whose type matches the contact point’s integration type:
| Grafana integration type | Notification target type |
|---|---|
slack | Slack |
pagerduty | PagerDuty |
email | Email (SMTP) |
webhook and prometheus-alertmanager | Webhook |
sns | SNS |
A contact point of any other integration type, such as Microsoft Teams, Opsgenie, Discord, or Telegram, shows Action required with the integration type. Cribl Search can’t map it, so create the Notification target by hand after the import if you still need that route.
A contact point that maps to a Webhook target shows Needs a template. Cribl Search has no default template for Webhook targets.
Rules that route to a Webhook target don’t deliver Notifications until you choose a template.
Cribl Search checks every mapping when you save it. It rejects a target that doesn’t exist, a target of the wrong type, and an unsupported integration type, and the error names the contact point and target involved. If the run discovered no contact points, the section reports No Contact Points were discovered for this run. If Cribl Search can’t load your Notification targets, the section shows Couldn’t load Notification targets, and the rest of the Map step remains usable.
Add a Target from a Contact Point
Select Add Target on a row that has no target selected. The button is disabled, with the tooltip Requires Notification target write access, if you can’t create Notification targets.
- In Create Notification Target for
<contact point>, review the pre-filled form. Cribl Search generates the target ID from the contact point’s name, replacing any character other than a letter, number, underscore, or hyphen with a hyphen. If that ID is already in use, Cribl Search adds a numeric suffix, so it never replaces an existing target. - Read the notes that precede the form. They list what Grafana reported that the target form can’t hold. Examples are the Slack channel, which is part of the Incoming Webhook URL, and the recipient addresses of an email contact point.
- Enter the credentials. Grafana redacts the credentials of contact points, so Cribl Search can’t copy them.
- Select Create Target.
Cribl Search creates the target as soon as you submit the form, and maps it to the contact point. The target remains available even if you abandon the migration. Credentials go only to the Notification targets, and never into the migration run, Review, or the exported report.
Cribl Search pre-fills these values from the contact point:
| Notification target type | Pre-filled from the contact point |
|---|---|
| PagerDuty | The severity, if it is info, warning, error, or critical. Otherwise you select one. |
| SNS | The destination type, set to topic, and the topic ARN. |
| Webhook | The default method, format, authentication, and backpressure behavior of a new Webhook target. |
Like the other selections on this step, Cribl Search saves the mapping when you select Run Assessment.
Review Compatibility
When assessment completes, Cribl Search opens Review Compatibility with a summary card for each status. Select a card to filter the table, and select Inspect on a row to open its details.
If Notifications are turned off on your deployment, Review shows the warning Notifications are turned off on this deployment. It explains that imported Monitors are created paused and don’t notify anyone, even after you enable them. The warning is informational and doesn’t block Create Import Plan… or the import.
Every selected resource, and every nested panel, query, and variable, receives one of these statuses:
| Status | Meaning |
|---|---|
| Ready | Cribl Search can import the resource with no known change in behavior. |
| Ready with changes | Cribl Search can import the resource, but something about it will change. The row states what. |
| Action required | You must resolve or explicitly skip the item before you can create an import plan. |
| Unsupported | Cribl Search can’t import the resource. Import a placeholder, or skip it. |
| Error | Assessment couldn’t classify or validate the resource. |
| Skipped | You excluded the resource, so it won’t be imported. |
Every result that isn’t Ready includes a reason code, the effect, and a next action.
Inspect a Dashboard
The inspection drawer breaks a Dashboard down into Panels, Variables, and Dependencies, and shows each query’s PromQL alongside its validation verdict. If you have Permission to read source snapshots, the inspection drawer includes the Source JSON tab.
Query validation distinguishes these outcomes, so an unavailable catalog never looks like a missing metric:
- The metric is absent from a complete catalog.
- The catalog couldn’t be listed in full, so the result is inconclusive.
- The query ran, but returned no data in the validation window.
- The query can’t run in Cribl Search.
- Validation timed out.
- Ingest renamed the metric, which is common for classic histogram metrics. Cribl Search validates the renamed form and reports the change.
- The query returns more series than a Dashboard panel displays.
Each verdict records the Cribl Search job ID, so you can correlate a result with Cribl Support.
To test against a different time range, select a Validation window and then Re-run validation. A panel with a no-data verdict also offers its own window and a validation rerun, so you can check one panel without reassessing the run.
Review Alert Rules
Each migration shows only the Dashboards tab or the Alert rules tab, depending on its resource type. The Alert rules table lists every selected rule with its folder, class, status, and reason.
Cribl Search imports the rules it can translate exactly, and assesses the rest:
| Class | Status | What Cribl Search does |
|---|---|---|
| Simple threshold | Ready, or Ready with changes | Imports the rule as a paused Monitor. |
| Multi-query | Action required | Doesn’t import the rule. Rebuild it as a Monitor by hand. |
| Classic conditions | Unsupported | Doesn’t import the rule. |
| Other expression rules, and recording rules | Unsupported | Doesn’t import the rule. |
A simple threshold rule has one PromQL query, an optional last reducer, and one threshold condition. Any other shape
would change what the alert fires on, so Cribl Search reports it instead of translating it.
Select Inspect on a rule to open its details. The drawer tags a rule that Imports as paused Monitor, and shows the query’s validation verdict. Extracted alert semantics lists the Reducer, Comparator, Threshold, For duration, Cadence, No-data behavior, and Exec-error behavior. The drawer also calls out the semantics that can’t carry over, such as the auto-resolve recovery model. A Linked dashboard tag names the Dashboard that the rule came from. The drawer describes the Notification routing of the rule in its own Notification routing section.
Cribl Search creates migrated Monitors through the same Permission and validation checks as a Monitor you build by hand.
Acknowledge Transformations
When Cribl Search rewrites part of a rule, or when the Notification routing differs from Grafana, the drawer lists each change under Transformations applied and Behavior differences. Cribl Search doesn’t import the rule until you acknowledge them.
- Review the changes the drawer lists.
- Select the acknowledgement check box. The text beside it changes to a message that begins Transformations acknowledged and states that the rule can be applied.
Notification Routing
The Notification routing section of the rule drawer shows where Grafana sent the alert and where Cribl Search sends it. It lists these rows when they apply to the rule:
| Row | What it shows |
|---|---|
| Grafana routing path | The contact point and its integration type, or Notification policy tree if the tree decides the route. A contact point that you didn’t map shows as not mapped to a Notification target. |
| Resulting Cribl routing | Direct to Notification target <target>, or Via the imported Notification policies. |
| Group wait | The wait before Cribl Search sends grouped Notifications. |
| Grouping | The labels Grafana grouped by. |
| Reminders dropped | The Grafana repeat and group intervals that Cribl Search doesn’t carry over. |
| Mute timings dropped | The recurring mute timings that aren’t carried over. |
Cribl Search chooses one of two routing modes for each rule:
- Direct: The labels the rule itself carries decide the route in the Grafana Notification policy tree. The imported Monitor sends to the mapped Notification target, and its Notification setting is on while the Monitor stays paused. A direct Monitor carries no grouping, so Cribl Search lists any grouping that Grafana applied as a difference.
- Policy: The route depends on a label that comes from the query’s series, or a policy node sets
continue. Cribl Search imports the tree as Notification policies instead. See Imported Notification Policies.
Cribl Search rounds a Grafana group wait up to whole minutes, because a Monitor groups in minutes. It lists the rounding only when it changes the value.
Cribl Search adds the alertname and grafana_folder labels to the metadata of each imported
Monitor, so that policy conditions on those labels resolve.
Each difference carries a code. You must acknowledge most of them before the import, as described in Acknowledge Transformations.
| Code | What it means | What you do |
|---|---|---|
routing-continue-fanout | A policy node sets continue. Cribl Search evaluates every later policy that matches, not only the sibling policies. | Acknowledge. |
routing-group-wait-rounded | Cribl Search rounded the group wait up to a whole minute. | Acknowledge. |
routing-reminders-dropped | The Grafana group interval or repeat interval isn’t carried over, so the Monitor sends no reminders. | Acknowledge. |
routing-mute-timings-dropped | A recurring mute timing isn’t carried over. | Acknowledge. |
routing-template-not-portable | Cribl Search uses the default template for the target type, so the Grafana message content doesn’t carry over. | Acknowledge. |
routing-series-label-matcher | A matcher reads a series label, so it resolves only for the labels that the Monitor query returns. | Acknowledge. |
routing-contact-point-unsupported | Cribl Search has no Notification target type for the contact point’s integration type. | Can’t be acknowledged. |
routing-webhook-template-missing | The mapped Webhook target has no default template, so the rule delivers nothing until you choose one. | Can’t be acknowledged. |
Imported Notification Policies
When any rule uses policy mode, Review shows an Imported Notification policies section. It lists the policies that Cribl Search will add, in the order that Cribl Search evaluates them, with these columns:
| Column | Description |
|---|---|
| Order | The position of the policy in the evaluation order. |
| Conditions | The conditions that the alert’s labels must match. A policy with no conditions shows Any alert (catch-all). |
| Targets | The Notification targets that receive matching alerts. |
| Final | Whether a match ends routing. |
| Group Wait | The wait, in minutes, before Cribl Search sends grouped Notifications. |
| Group By | The labels that group alerts. |
Cribl Search builds the policies from the Grafana tree like this:
- Each node of the tree becomes one policy, and the policies for the deepest nodes come first. The conditions of a policy are the matchers along the path to its node, joined with AND.
- A policy is Final unless its Grafana node sets
continue. - The default policy at the root of the tree becomes a final catch-all policy at the end of the block.
- A node whose receiver isn’t mapped to a Notification target produces no policy, and the section names the reason.
Cribl Search adds the block above the highest order that your existing policies use. It never changes the order of an existing policy.
If the block conflicts with your existing policies, the section shows the warning This block conflicts with the Notification policies already in place. with one of these reason codes:
| Reason code | What it means |
|---|---|
target-id-collision | A policy with the same ID already exists. |
policy-shadowed-by-catch-all | An existing final catch-all policy with a lower order would end routing before the new block. |
target-modified | Someone edited a policy from an earlier run in Cribl Search. |
Cribl Search writes nothing for a conflicting block unless you explicitly choose to replace it.
Create and Run the Import Plan
Resolve or explicitly skip every Action required item, then:
- Select Create Import Plan….
- In Confirm import plan, review the plan revision, the Collection, Dashboard, and panel counts, and the warning that the import isn’t atomic.
- Select Start Import.
The import starts only from this confirmation. Opening Import directly reports that the import hasn’t started.
Changing your selection or mapping produces a new plan revision.
Cribl Search writes Dashboards one at a time, so an import can partially succeed. Canceling stops further writes at the next safe point, and it doesn’t undo Dashboards that were already created or updated.
When the run finishes, Cribl Search opens Results.
Review the Results
Results titles the run Import Complete or Import Completed with Warnings, or Import cancelled if you canceled it. When every item is unchanged, the title begins Rerun complete and states that no changes were needed. The page shows a count for each outcome and a row per item with its source and its target ID:
| Outcome | Meaning |
|---|---|
| Ensured | Cribl Search created the Collection if it was missing. Dashboards share a Collection. |
| Created | Cribl Search created a new Dashboard. |
| Updated | Cribl Search updated an existing Dashboard. |
| Up to date | Nothing changed, so Cribl Search wrote nothing. |
| Placeholder | Cribl Search imported a placeholder in place of unsupported content. |
| Skipped | You excluded the item. |
| Blocked | A conflict or a failed dependency prevented the write. |
| Failed | The write failed. The row states whether a retry is safe. |
Imported Dashboards are available immediately in Cribl Search, in the Collections you mapped.
Alert rules appear in their own section, with the class and status from the assessment and the outcome of the write. A rule that produced a Monitor offers an Open Monitor link. A rule that Cribl Search didn’t import states its reason instead, and never reports success.
Every migrated Monitor arrives paused, so it can’t fire until you review it. To start alerting on one, open the Monitor and enable it. See Monitors.
A Monitor that imported in direct mode already has its Notification target set and its Notifications turned on, so enabling it is the only step left. Confirm that Notifications are turned on for your deployment, or the Monitor still notifies no one.
You can export a redacted .json report of the run for support or automation. The report carries stable reason codes,
the Notification routing that the run recreated, and no credentials.
Deleting a run removes the run record and its stored snapshots, but not the Dashboards it imported. Deleting a run that’s still discovering or importing cancels it first, and you might need to delete it again after the run is canceled.
Rerun a Migration
Cribl Search matches previously imported Dashboards by their Grafana identity rather than their name, so renaming a Dashboard in either system doesn’t create a duplicate. On a later run:
- A Dashboard that hasn’t changed on either side is Up to date, and Cribl Search writes nothing.
- A Dashboard that changed in Grafana updates its existing target, as long as no one edited that target in Cribl Search.
- A Dashboard you edited in Cribl Search is reported as a conflict, with the reason
target-modified. - An unrelated Dashboard that already owns the target ID blocks the write.
- Cribl Search never deletes a target automatically, even when the Grafana Dashboard is gone.
To replace your edits in Cribl Search with the Grafana version, select Overwrite on Import on the row during review. The row is tagged Will overwrite. Leave the option clear to keep your Cribl Search edits.
With Overwrite on Import selected, the import replaces the edited Dashboard with the Grafana version.
Alert rules reconcile the same way. A rule that hasn’t changed writes nothing, and a Monitor that someone edited in Cribl Search is reported as a conflict that you can keep or overwrite.
Imported Notification policies follow the rules in Imported Notification Policies. Cribl Search reports an ID collision or an edited policy as a conflict, and it never renumbers a policy that already exists.
Enable Migration Mode
After a Dashboards import, Results can offer Migration mode for each Dataset you mapped. When local storage doesn’t cover a query, Cribl Search sends the whole query to a Prometheus Dataset Provider. It never merges local and remote results.
Migration mode is off by default. To turn it on for a Dataset:
- In the Migration mode section, find the row for the Dataset.
- Under Source Prometheus provider, select a Prometheus Dataset Provider. Until you do, the Enable toggle stays inactive.
- Turn on Enable.
The change applies right away, with no separate save. The row’s status becomes Migration mode enabled, and Source Prometheus provider locks. Turn Enable off to restore local-only queries and unlock the Dataset Provider.
If your Organization has no Prometheus Dataset Provider, the section reports No Prometheus Dataset Providers available. Create one, or ask an administrator for access to one, and then return here. If a change can’t be saved, the row shows an error and the toggle returns to its previous state.
You can also configure migration mode later, on the metrics Dataset itself.
Next Steps
- Explore Metrics in Cribl Search to query the metrics behind your imported Dashboards.
- Add a Metrics Query to a Dashboard to extend an imported Dashboard with more panels.
- Create Monitors to replace the Grafana alert rules that Cribl Search couldn’t import.
- Manage Monitor Notifications to edit the Targets, Templates, and Policies that the migration created or mapped.