Skip to content

Grafana.mdx

Latest commit

 

History

History
452 lines (363 loc) · 12.3 KB

Grafana.mdx

File metadata and controls

452 lines (363 loc) · 12.3 KB
title Grafana

Connect Grafana alerts, alert rules, and data queries to SuperPlane workflows

import { CardGrid, LinkCard } from "@astrojs/starlight/components";

Triggers

Actions

Instructions

Setup steps:

  1. In Grafana, go to Administration → Users and access → Service Accounts, select Add service account.

    Service Account Role:
    While naming the service account, go to Roles → Basic roles and select Admin.

    Navigate to the created service account and select Add service account token. Name it and set an expiration period then click Generate token. This is your Service Account Token.

  2. Use your Grafana root URL as Base URL (for example https://grafana.example.com).

  3. Fill in Base URL and Service Account Token below, then save.

On Alert Firing

The On Alert Firing trigger starts a workflow when Grafana Unified Alerting sends a firing alert webhook.

Setup

  1. SuperPlane automatically creates or updates a Grafana Webhook contact point and notification policy route for this trigger when provisioning succeeds.
  2. SuperPlane manages webhook bearer authentication automatically.
  3. Provisioning requires a Grafana integration with Base URL and Service Account Token and sufficient permissions for alerting and provisioning APIs.

Configuration

  • Alert Names: Optional exact alert name filters

Event Data

The trigger emits the full Grafana webhook payload, including:

  • status (firing/resolved)
  • alerts array with labels and annotations
  • groupLabels, commonLabels, commonAnnotations
  • externalURL and other alerting metadata

Example Data

{
  "data": {
    "alerts": [
      {
        "annotations": {
          "summary": "Error rate above threshold"
        },
        "labels": {
          "alertname": "HighErrorRate",
          "service": "api"
        },
        "status": "firing"
      }
    ],
    "commonLabels": {
      "alertname": "HighErrorRate"
    },
    "externalURL": "http://grafana.local",
    "ruleUid": "alert_rule_uid",
    "status": "firing",
    "title": "High error rate"
  },
  "timestamp": "2026-02-12T16:18:03.362582388Z",
  "type": "grafana.alert.firing"
}

Create Alert Rule

The Create Alert Rule component creates a Grafana-managed alert rule using the Alerting Provisioning HTTP API.

Use Cases

  • Monitoring onboarding: create baseline alerts when a new service or environment is provisioned
  • Incident automation: create temporary alert rules during an incident or validation workflow
  • Policy rollout: standardize alert coverage across teams using a shared rule definition

Configuration

  • Title: Human-readable alert name shown in Grafana
  • Folder: Existing Grafana folder that should contain the rule
  • Rule Group: Grafana rule group to create the rule in
  • Data Source: Existing Grafana data source the query should use
  • Query: Expression Grafana evaluates when checking the alert
  • Labels / Annotations: Optional routing and context metadata attached to the rule

Output

Returns the created Grafana alert rule object, including identifiers and evaluation metadata.

Example Output

{
  "data": {
    "annotations": {
      "summary": "High error rate detected"
    },
    "condition": "A",
    "data": [
      {
        "datasourceUid": "prometheus-main",
        "model": {
          "editorMode": "code",
          "expr": "sum(rate(http_requests_total{status=~\"5..\"}[5m]))",
          "intervalMs": 1000,
          "maxDataPoints": 43200,
          "refId": "A"
        },
        "queryType": "",
        "refId": "A",
        "relativeTimeRange": {
          "from": 300,
          "to": 0
        }
      }
    ],
    "execErrState": "Alerting",
    "folderUID": "infra",
    "for": "5m",
    "id": 42,
    "isPaused": false,
    "labels": {
      "service": "api",
      "severity": "critical"
    },
    "noDataState": "NoData",
    "orgID": 1,
    "ruleGroup": "service-health",
    "title": "High error rate",
    "uid": "cergr5pm79hj4d",
    "updated": "2026-03-31T10:20:30Z"
  },
  "timestamp": "2026-03-31T10:20:30Z",
  "type": "grafana.alertRule"
}

Delete Alert Rule

The Delete Alert Rule component deletes a Grafana-managed alert rule using the Alerting Provisioning HTTP API.

Use Cases

  • Alert cleanup: remove temporary or obsolete rules after a rollout or incident
  • Service retirement: delete rules that are no longer needed when an environment is decommissioned
  • Controlled cleanup: pair deletions with approvals, notifications, or audit workflows

Configuration

  • Alert Rule: The Grafana alert rule UID to delete

Output

Returns a confirmation object with the deleted alert rule UID, title, and deletion status.

Example Output

{
  "data": {
    "deleted": true,
    "title": "High error rate",
    "uid": "cergr5pm79hj4d"
  },
  "timestamp": "2026-03-31T10:24:30Z",
  "type": "grafana.alertRuleDeleted"
}

Get Alert Rule

The Get Alert Rule component fetches a Grafana-managed alert rule using the Alerting Provisioning HTTP API.

Use Cases

  • Configuration review: inspect the current source of truth before changing a rule
  • Workflow enrichment: include alert rule details in notifications, tickets, or approvals
  • Drift checks: compare the current Grafana rule against an expected configuration

Configuration

  • Alert Rule: The Grafana alert rule UID to retrieve

Output

Returns the full Grafana alert rule object, including title, folder, group, condition, queries, labels, and annotations.

Example Output

{
  "data": {
    "annotations": {
      "summary": "High error rate detected"
    },
    "condition": "A",
    "data": [
      {
        "datasourceUid": "prometheus-main",
        "model": {
          "editorMode": "code",
          "expr": "sum(rate(http_requests_total{status=~\"5..\"}[5m]))",
          "intervalMs": 1000,
          "maxDataPoints": 43200,
          "refId": "A"
        },
        "queryType": "",
        "refId": "A",
        "relativeTimeRange": {
          "from": 300,
          "to": 0
        }
      }
    ],
    "execErrState": "Alerting",
    "folderUID": "infra",
    "for": "5m",
    "id": 42,
    "isPaused": false,
    "labels": {
      "service": "api",
      "severity": "critical"
    },
    "noDataState": "NoData",
    "orgID": 1,
    "ruleGroup": "service-health",
    "title": "High error rate",
    "uid": "cergr5pm79hj4d",
    "updated": "2026-03-31T10:20:30Z"
  },
  "timestamp": "2026-03-31T10:20:30Z",
  "type": "grafana.alertRule"
}

List Alert Rules

The List Alert Rules component lists Grafana-managed alert rules using the Alerting Provisioning HTTP API.

Use Cases

  • Alert audits: review which Grafana alert rules currently exist
  • Workflow enrichment: send alert inventories to Slack, Jira, or documentation steps
  • Follow-up automation: feed alert rule summaries into downstream review or cleanup workflows

Configuration

This component does not require configuration.

Output

Returns an object containing the list of Grafana alert rule summaries, including each rule UID and title.

Example Output

{
  "data": {
    "alertRules": [
      {
        "title": "High error rate",
        "uid": "cergr5pm79hj4d"
      },
      {
        "title": "High latency",
        "uid": "aer9k2pm71sh2b"
      },
      {
        "title": "Service unavailable",
        "uid": "bfg4m1rt63hj8q"
      }
    ]
  },
  "timestamp": "2026-03-31T10:24:30Z",
  "type": "grafana.alertRules"
}

Query Data Source

The Query Data Source component executes a query against a Grafana data source using the Grafana Query API.

Use Cases

  • Metrics investigation: Run PromQL or other datasource queries from workflows
  • Alert validation: Validate alert conditions before escalation
  • Incident context: Pull current metrics into incident workflows

Configuration

  • Data Source: The Grafana data source to query
  • Query: The datasource query (PromQL, InfluxQL, etc.)
  • Time From / Time To: Optional range as Grafana relative times (e.g. now-5m, now), RFC3339 timestamps, or local datetimes (2006-01-02T15:04) with Timezone below
  • Timezone: Required for local datetime strings without an offset; ignored for relative times and RFC3339 values
  • If omitted, SuperPlane defaults the query to the last 5 minutes
  • Format: Optional query format (depends on the datasource)

Output

Returns the Grafana query API response JSON.

Example Output

{
  "data": {
    "results": {
      "A": {
        "frames": [
          {
            "data": {
              "values": [
                [
                  "2026-02-07T08:00:00Z",
                  "2026-02-07T08:01:00Z"
                ],
                [
                  1,
                  1
                ]
              ]
            },
            "schema": {
              "fields": [
                {
                  "name": "time",
                  "type": "time"
                },
                {
                  "name": "value",
                  "type": "number"
                }
              ]
            }
          }
        ]
      }
    }
  },
  "timestamp": "2026-02-12T16:18:03.362582388Z",
  "type": "grafana.query.result"
}

Update Alert Rule

The Update Alert Rule component updates a Grafana-managed alert rule using the Alerting Provisioning HTTP API.

Use Cases

  • Threshold tuning: refine alert conditions after incidents or noisy periods
  • Ownership changes: update labels and annotations used for routing and context
  • Rollout safety: adjust alert rules during migrations or environment transitions

Configuration

  • Alert Rule: The Grafana alert rule UID to update
  • All other fields are optional: only the values you provide will be changed
  • Folder / Rule Group: Optional location changes for the rule in Grafana
  • Data Source / Query: Optional query details Grafana evaluates
  • Labels / Annotations: Optional metadata to update alongside the rule

Output

Returns the updated Grafana alert rule object after the provisioning API applies the change.

Example Output

{
  "data": {
    "annotations": {
      "summary": "High error rate detected"
    },
    "condition": "A",
    "data": [
      {
        "datasourceUid": "prometheus-main",
        "model": {
          "editorMode": "code",
          "expr": "sum(rate(http_requests_total{status=~\"5..\"}[5m]))",
          "intervalMs": 1000,
          "maxDataPoints": 43200,
          "refId": "A"
        },
        "queryType": "",
        "refId": "A",
        "relativeTimeRange": {
          "from": 300,
          "to": 0
        }
      }
    ],
    "execErrState": "Alerting",
    "folderUID": "infra",
    "for": "5m",
    "id": 42,
    "isPaused": false,
    "labels": {
      "service": "api",
      "severity": "critical"
    },
    "noDataState": "NoData",
    "orgID": 1,
    "ruleGroup": "service-health",
    "title": "High error rate",
    "uid": "cergr5pm79hj4d",
    "updated": "2026-03-31T10:20:30Z"
  },
  "timestamp": "2026-03-31T10:20:30Z",
  "type": "grafana.alertRule"
}