Grafana Integration

Connect Grafana Cloud or self-hosted Grafana to Aurora for alert management and observability insights

Integrate Aurora with Grafana to receive alerts, manage incidents, and perform AI-driven root cause analysis on your monitoring data.

Authentication

Grafana uses API Token (Bearer token) authentication.

Prerequisites

• Grafana Cloud account or self-hosted Grafana instance
• Permissions to create service accounts (Grafana Cloud) or API tokens (self-hosted)

Setup Steps

1. Create Service Account (Grafana Cloud)

   1. Go to Grafana Cloud and select your stack
   2. Navigate to Administration > Service accounts
   3. Click Add service account
   4. Name: Aurora, Role: Viewer
   5. Click Add service account token
   6. Copy the generated token (you won’t see it again)
2. Create API Token (Self-Hosted)

   For self-hosted Grafana:

   1. Go to Configuration > API Keys
   2. Click Add API key
   3. Name: Aurora, Role: Viewer
   4. Copy the generated token
3. Connect to Aurora

   1. In Aurora, navigate to Integrations > Grafana
   2. Enter your Grafana base URL (e.g., https://your-stack.grafana.net)
   3. Paste your API token
   4. Click Connect

Configuration

No environment variables are required. API tokens are entered through the Aurora UI.

Self-Hosted Grafana

For self-hosted instances, provide your Grafana URL during connection:

https://grafana.yourcompany.com

The URL will be automatically normalized (protocol added if missing, trailing slashes removed).

Webhook Setup (Optional)

Receive real-time alerts from Grafana Alerting:

1. Get Webhook URL

   In Aurora’s Grafana integration page, copy your unique webhook URL:

   https://your-aurora-domain/grafana/alerts/webhook/{user_id}
   
2. Create Contact Point

   1. In Grafana, go to Alerting > Contact points
   2. Click + Add contact point
   3. Name: Aurora
   4. Type: Webhook
   5. URL: Paste your Aurora webhook URL
   6. Click Test to verify connectivity
   7. Save the contact point
3. Configure Notification Policy

   1. Go to Alerting > Notification policies
   2. Edit the default policy or create a new one
   3. Add the Aurora contact point to receive alerts
   4. Save the policy

Development with ngrok

For local development:

.env

NGROK_URL=https://your-ngrok-url.ngrok-free.app

Start ngrok:

ngrok http 5080

What Aurora Can Query

Once connected, Aurora can:

Organization Info

• Retrieve organization details
• Verify connection status
• Access user profile information

API Endpoint: GET /grafana/status

Response:

{
  "connected": true,
  "org": {
    "id": 1,
    "name": "Your Organization"
  },
  "user": {
    "email": "[e-mail]",
    "name": "Aurora"
  },
  "baseUrl": "https://your-stack.grafana.net"
}

Webhook Alerts

• Receive real-time alerts from Grafana
• Auto-create incidents from firing alerts
• Track alert state transitions (firing, resolved)
• Correlate related alerts
• Generate AI-powered root cause analysis

Ingested Data:

• Alert UID and title
• Alert state (alerting, resolved, no_data)
• Rule name and URL
• Dashboard and panel URLs
• Labels and annotations
• Alert values and evaluation info

API Endpoint: GET /grafana/alerts

Parameters:

• limit - Number of alerts (default: 50)
• offset - Pagination offset (default: 0)
• state - Filter by state (alerting, resolved, no_data)

Response:

{
  "alerts": [
    {
      "id": 123,
      "alertUid": "abc123",
      "title": "High CPU Usage",
      "state": "alerting",
      "ruleName": "CPU Alert",
      "ruleUrl": "https://grafana.example.com/...",
      "dashboardUrl": "https://grafana.example.com/d/...",
      "panelUrl": "https://grafana.example.com/d/.../...",
      "receivedAt": "2026-03-03T10:30:00Z",
      "payload": {...}
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Troubleshooting

Connection Failed

• Verify API token is valid and not expired
• Check base URL is correct and accessible
• Ensure service account has at least Viewer role
• For self-hosted: verify Aurora can reach your Grafana instance

Webhook Not Receiving Alerts

• Verify NGROK_URL is set correctly (for local development)
• Ensure ngrok tunnel is running
• Check contact point is configured with correct webhook URL
• Send a test notification from Grafana contact point settings
• Verify notification policy routes alerts to Aurora contact point

Invalid Base URL Error

• Use format: https://your-stack.grafana.net
• Do not include /api or other paths
• Ensure URL uses HTTPS (HTTP will be auto-upgraded)

API Reference

Base Path: /grafana

Method	Endpoint	Description
POST	/connect	Connect Grafana account
GET	/status	Check connection status
DELETE	/disconnect	Remove Grafana connection
GET	/alerts	List webhook alerts
POST	/alerts/webhook/{user_id}	Receive webhooks
GET	/alerts/webhook-url	Get webhook URL

For detailed information about Grafana APIs, see:

• Grafana HTTP API
• Grafana Alerting