Grafana Integration

Connect Grafana to enable the AI agent to query dashboards, metrics, and alerts during investigations.

Capabilities

Once connected, the AI agent can:

Capability	Description
Query Metrics	Fetch data from configured data sources
View Dashboards	Access dashboard panels and visualizations
Check Alerts	Review alert rules and their current state
Search Annotations	Find annotations marking events

Prerequisites

• A Grafana instance (Cloud or self-hosted)
• A Service Account with API access
• Viewer or higher permissions

Setup

1

Create a Service Account

1. Log in to your Grafana instance
2. Navigate to Administration → Service accounts
3. Click Add service account
4. Name it (e.g., "Autoheal Integration")
5. Assign the Viewer role

2

Generate API Token

1. In the service account, click Add token
2. Give it a name and set expiration (or no expiration)
3. Copy the generated token immediately

3

Add Integration in Autoheal

1. Go to Integrations in Autoheal
2. Click Grafana
3. Enter a name (e.g., "Production Grafana")

4

Configure Credentials

Enter the following:

• URL: Your Grafana URL (e.g., https://your-org.grafana.net)
• API Token: The service account token you created

5

Test and Save

Click Test Connection to verify, then Save.

Required Permissions

The service account needs:

Permission	Why It's Needed
Viewer role	Basic read access to dashboards and data
Data source access	Query underlying data sources

note

For self-hosted Grafana, ensure the service account has access to the specific data sources you want to query.

Grafana Cloud vs Self-Hosted

Grafana Cloud

Use your Grafana Cloud URL:

https://your-org.grafana.net

Self-Hosted Grafana

Use your Grafana server URL:

https://grafana.your-company.com

Ensure the URL is accessible from Autoheal (check firewall rules).

Example Queries

Once connected, you can ask the AI agent:

Show me the request rate from the API dashboard

What alerts are currently firing in Grafana?

Get CPU metrics for the web servers from the last 30 minutes

Grafana Version Compatibility

The integration automatically handles different Grafana API versions. Grafana 11.x introduced changes to datasource proxy endpoints that are transparently managed by the agent.

Version Detection

The agent can detect your Grafana version to optimize API calls:

What version of Grafana are we using?

This returns version information and API compatibility mode.

Automatic Fallback

The integration uses version-aware endpoint selection with automatic fallback:

• Grafana 11.x and later: Uses ID-based datasource proxy (primary), falls back to UID-based if needed
• Grafana 10.x and earlier: Uses UID-based datasource proxy (primary), falls back to ID-based if needed

This ensures compatibility across different Grafana versions without requiring manual configuration.

Troubleshooting

401 Unauthorized

• Verify the API token is correct and hasn't expired
• Check that the service account hasn't been disabled
• Ensure the token was copied completely

Connection Refused (Self-Hosted)

• Verify the Grafana URL is correct
• Check firewall rules allow access from Autoheal
• Ensure Grafana is running and accessible

No Dashboards Found

• Verify the service account has Viewer permissions
• Check folder permissions for dashboards

404 Errors on Prometheus Queries

If you receive 404 errors specifically on Prometheus queries:

1. The agent automatically handles version-specific API formats
2. The issue may be with datasource configuration or permissions
3. Verify the datasource UID is correct using the "List data sources" query
4. Check that the service account has access to the Prometheus datasource

Note: Loki queries use a different endpoint format and typically don't have this issue.