> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.
# Netdata Integration
> Connect Netdata Cloud to Aurora for real-time infrastructure monitoring and AI-powered alert analysis
Integrate Aurora with Netdata Cloud to receive infrastructure alerts, monitor system metrics, and perform automated root cause analysis on performance issues.
## Authentication
Netdata uses **API Token** authentication for Netdata Cloud.
### Prerequisites
* Netdata Cloud account
* Access to at least one Netdata Space
### Setup Steps
1. Go to [Netdata Cloud](https://app.netdata.cloud/)
2. Click your avatar and select **Account Settings**
3. Navigate to **API Tokens**
4. Click **Create Token**
5. Name: `Aurora`
6. Copy the generated token (you won't see it again)
Add to your `.env` file:
```bash .env theme={null}
NEXT_PUBLIC_ENABLE_NETDATA=true
```
Restart Aurora:
```bash theme={null}
make down && make dev
```
1. In Aurora, navigate to **Integrations** > **Netdata**
2. Enter your API token
3. (Optional) Enter your Space name
4. Click **Connect**
## Configuration
### Environment Variables
```bash .env theme={null}
# Required: Enable Netdata integration
NEXT_PUBLIC_ENABLE_NETDATA=true
# For local webhook development
NGROK_URL=https://your-ngrok-url.ngrok-free.app
```
The Netdata integration will not appear in Aurora unless `NEXT_PUBLIC_ENABLE_NETDATA=true` is set.
## Webhook Setup
Receive real-time alerts from Netdata Cloud:
### Local Development Setup
Netdata webhooks cannot reach `localhost:5080` directly. Use ngrok:
```bash theme={null}
ngrok http 5080
```
Copy the HTTPS URL and add to `.env`:
```bash .env theme={null}
NGROK_URL=https://abc123.ngrok-free.app
```
In Aurora's Netdata integration page, copy your webhook URL:
```
https://abc123.ngrok-free.app/netdata/alerts/webhook/{user_id}
```
1. Go to [Netdata Cloud](https://app.netdata.cloud/)
2. Select your Space
3. Go to **Space settings** > **Alert notifications**
4. Click **Add configuration**
5. Method: `Webhook`
6. URL: Paste your Aurora webhook URL
7. Save the configuration
Send a test notification from Netdata Cloud to verify connectivity. Aurora will store the verification token automatically.
### Production Setup
In production, webhooks use your production backend URL automatically.
Webhook URL format:
```
https://your-aurora-domain/netdata/alerts/webhook/{user_id}
```
## What Aurora Can Query
Once connected, Aurora can:
### Connection Status
* Verify API token is valid
* Check Space configuration
* View base URL
**API Endpoint:** `GET /netdata/status`
**Response:**
```json theme={null}
{
"connected": true,
"baseUrl": "https://app.netdata.cloud",
"spaceName": "Production Infrastructure"
}
```
### Webhook Alerts
* Receive real-time alerts from Netdata agents
* Auto-create incidents from critical alerts
* Track alert status transitions
* Correlate alerts across nodes
* Generate AI-powered root cause analysis
**Ingested Data:**
* Alert name and status (WARNING, CRITICAL, CLEAR)
* Chart and metric information
* Host and node details
* Space and room context
* Alert value and thresholds
* Alert message and description
**API Endpoint:** `GET /netdata/alerts`
**Parameters:**
* `limit` - Number of alerts (default: 50)
* `offset` - Pagination offset (default: 0)
* `status` - Filter by status (WARNING, CRITICAL, CLEAR)
**Response:**
```json theme={null}
{
"alerts": [
{
"id": 123,
"alertName": "system.cpu.user",
"status": "CRITICAL",
"chart": "system.cpu",
"host": "prod-server-01",
"space": "Production",
"room": "Web Servers",
"value": "95.5",
"message": "High CPU usage detected",
"receivedAt": "2026-03-03T10:30:00Z",
"payload": {...}
}
],
"total": 42,
"limit": 50,
"offset": 0
}
```
### Webhook Verification
* Get webhook verification token
* Required by Netdata for webhook authentication
* Token is automatically stored when test notification is sent
**API Endpoint:** `GET /netdata/alerts/webhook-url`
**Response:**
```json theme={null}
{
"webhookUrl": "https://your-aurora-domain/netdata/alerts/webhook/{user_id}",
"verificationToken": "abc123def456..."
}
```
The verification token is automatically extracted and stored when Netdata sends a test notification. You don't need to manually configure it.
## Troubleshooting
**"Netdata connector not enabled"**
* Ensure `NEXT_PUBLIC_ENABLE_NETDATA=true` is set in `.env`
* Restart Aurora services with `make down && make dev`
* Check that the environment variable is loaded correctly
**Connection Failed**
* Verify API token is correct and not expired
* Check that token was created in Netdata Cloud (not a local agent)
* Ensure you have access to at least one Space
**Webhook Not Receiving Alerts**
* Verify `NGROK_URL` is set correctly (local development)
* Ensure ngrok tunnel is running
* Check webhook URL in Netdata matches Aurora UI
* Send test notification from Netdata Cloud
* Verify alert notification rules are configured in your Space
**Missing Verification Token**
* Send a test notification from Netdata Cloud webhook settings
* Aurora will automatically extract and store the token
* Refresh the Aurora Netdata integration page to see the token
**Alerts Not Creating Incidents**
* Check Aurora logs for webhook processing errors
* Verify alert payload contains required fields (alert name, status)
* Ensure incident creation is enabled in Aurora settings
## API Reference
**Base Path:** `/netdata`
| Method | Endpoint | Description |
| ------ | --------------------------- | ------------------------- |
| POST | `/connect` | Connect Netdata account |
| GET | `/status` | Check connection status |
| DELETE | `/disconnect` | Remove Netdata connection |
| GET | `/alerts` | List webhook alerts |
| POST | `/alerts/webhook/{user_id}` | Receive webhooks |
| GET | `/alerts/webhook-url` | Get webhook URL and token |
For detailed Netdata documentation, see:
* [Netdata Cloud Documentation](https://learn.netdata.cloud/)
* [Netdata Alert Notifications](https://learn.netdata.cloud/docs/alerts-&-notifications/notifications)