Grafana Dashboard Integration

This guide explains how to integrate Grafana dashboards into the OpportunityDAO admin panel.

Overview

The integration allows you to embed Grafana dashboards directly into the Reserves page, providing real-time monitoring of:

• Reserve account balances
• Transaction history
• Performance metrics
• Custom analytics

Architecture

The integration uses a proxy pattern for security:

1. Frontend requests dashboard content
2. Backend proxies requests to Grafana with service token
3. Service token never exposed to client
4. Only authenticated founders can access

┌─────────┐      ┌──────────┐      ┌─────────┐
│ Browser │ ───> │ Next.js  │ ───> │ Grafana │
│         │ <─── │ Backend  │ <─── │         │
└─────────┘      └──────────┘      └─────────┘
                  (with token)

Setup Instructions

1. Create Grafana Service Account

1. Log into your Grafana instance as an admin
2. Navigate to Administration → Service accounts
3. Click Add service account
4. Configure the account:
   • Name: OpportunityDAO Embed
   • Role: Viewer (or Editor if needed)
   • Description: Service account for embedding dashboards
5. Click Create
6. Click Add service account token
7. Set token name (e.g., "Production") and expiration
8. Click Generate token
9. Copy the token immediately - it won't be shown again!

2. Find Your Dashboard UID

1. Open the dashboard you want to embed
2. Click the Settings gear icon (⚙️) in the top right
3. Look at the URL: /d/{UID}/dashboard-name
4. Or find the UID in the General section
5. Copy the UID (e.g., abc123def456)

3. Configure Environment Variables

Add these variables to your .env file:

# Enable Grafana integration
NEXT_PUBLIC_GRAFANA_ENABLED=true

# Your Grafana instance URL (without trailing slash)
NEXT_PUBLIC_GRAFANA_URL=https://grafana.yourdomain.com

# Dashboard UID from step 2
NEXT_PUBLIC_GRAFANA_DASHBOARD_UID=abc123def456

# Server-side configuration (DO NOT prefix with NEXT_PUBLIC_)
GRAFANA_URL=https://grafana.yourdomain.com
GRAFANA_SERVICE_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxxx

4. Configure Grafana Embedding Settings

In your Grafana instance:

1. Go to Configuration → Settings

2. Find the [security] section

3. Enable anonymous access for embedding (optional):

   [auth.anonymous]
   enabled = true
   org_role = Viewer

4. Or configure CORS if needed:

   [security]
   allow_embedding = true
   cookie_samesite = none
   cookie_secure = true

5. Restart Your Application

npm run dev  # Development
# or
npm run build && npm start  # Production

Usage

Basic Dashboard Embed

The dashboard will automatically appear on the Reserves page (/admin/reserves) when configured.

Custom Dashboard Usage

You can embed dashboards in other pages using the GrafanaDashboard component:

import GrafanaDashboard from '@/components/GrafanaDashboard';

export default function MyPage() {
  return (
    <div>
      <h1>Custom Dashboard</h1>
      <GrafanaDashboard
        dashboardUid="abc123def456"
        theme="light"
        height="800px"
        refreshInterval={30000}
        from="now-24h"
        to="now"
      />
    </div>
  );
}

Component Props

Prop	Type	Default	Description
dashboardUid	string	required	Dashboard UID from Grafana
panelId	number	undefined	Specific panel ID to show (omit for full dashboard)
theme	'light' | 'dark'	'light'	Dashboard theme
height	string	'600px'	Height of dashboard iframe
refreshInterval	number	undefined	Auto-refresh interval in milliseconds
from	string	'now-6h'	Time range start (Grafana format)
to	string	'now'	Time range end (Grafana format)

Embed Single Panel

To embed just one panel instead of the full dashboard:

<GrafanaDashboard
  dashboardUid="abc123def456"
  panelId={2}  // Panel ID from Grafana
  height="400px"
/>

Finding Panel ID:

1. Open dashboard in Grafana
2. Click panel title → Edit
3. Look at URL: ?editPanel={panelId}

API Endpoints

Grafana Proxy API

The backend provides a proxy API for secure Grafana requests:

GET /api/admin/grafana/proxy?path={grafana-path}

• Proxies GET requests to Grafana
• Adds service token authentication
• Requires founder authentication

POST /api/admin/grafana/proxy?path={grafana-path}

• Proxies POST requests to Grafana
• Adds service token authentication
• Requires founder authentication

Security Considerations

1. Service Token Storage

   • Service token stored server-side only
   • Never exposed to client
   • Use environment variables, not code

2. Access Control

   • Only founders can access Grafana proxy
   • Authentication checked on every request
   • Audit log all access (future enhancement)

3. Token Permissions

   • Use minimum required permissions (Viewer)
   • Set token expiration
   • Rotate tokens regularly

4. CORS & Embedding

   • Configure Grafana embedding settings
   • Use HTTPS in production
   • Set appropriate cookie settings

Troubleshooting

Dashboard Not Showing

1. Check environment variables:

   echo $NEXT_PUBLIC_GRAFANA_ENABLED
   echo $NEXT_PUBLIC_GRAFANA_URL
   echo $NEXT_PUBLIC_GRAFANA_DASHBOARD_UID

2. Verify service token:

   curl -H "Authorization: Bearer $GRAFANA_SERVICE_TOKEN" \
        $GRAFANA_URL/api/dashboards/uid/$DASHBOARD_UID

3. Check browser console for errors

CORS Errors

If you see CORS errors in the console:

1. Configure Grafana allow_embedding = true
2. Set cookie_samesite = none and cookie_secure = true
3. Ensure Grafana URL uses HTTPS

Authentication Issues

If you get 401 errors:

1. Verify service token is valid
2. Check token hasn't expired
3. Ensure service account has Viewer role
4. Verify dashboard is accessible with the token

iframe Not Loading

If the iframe appears but doesn't load:

1. Check Grafana embedding settings
2. Verify dashboard UID is correct
3. Look for X-Frame-Options errors
4. Check browser console for security errors

Example Dashboards

Reserves Monitoring Dashboard

Create a Grafana dashboard with these panels:

1. Total Reserves Balance (Stat panel)

   • Shows current total balance across all accounts
   • Color-coded thresholds

2. Balance by Account (Bar chart)

   • Breakdown by broker/wallet
   • Sortable

3. 24h Balance Changes (Time series)

   • Balance trends over time
   • Multiple series per account

4. Recent Transactions (Table)

   • Latest deposits/withdrawals
   • Transaction details

5. Reserve Ratio (Gauge)

   • Reserves vs. deployed capital
   • Warning thresholds

Advanced Usage

Multiple Dashboards

You can embed multiple dashboards on the same page:

<div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
  <GrafanaDashboard
    dashboardUid="overview-uid"
    height="400px"
  />
  <GrafanaDashboard
    dashboardUid="details-uid"
    height="400px"
  />
</div>

Dynamic Time Ranges

Control time range programmatically:

const [timeRange, setTimeRange] = useState({ from: 'now-6h', to: 'now' });

<GrafanaDashboard
  dashboardUid="abc123def456"
  from={timeRange.from}
  to={timeRange.to}
/>

Custom Refresh Intervals

Different refresh rates for different dashboards:

// Real-time (10 seconds)
<GrafanaDashboard dashboardUid="realtime-uid" refreshInterval={10000} />

// Standard (30 seconds)
<GrafanaDashboard dashboardUid="standard-uid" refreshInterval={30000} />

// Slow (5 minutes)
<GrafanaDashboard dashboardUid="historical-uid" refreshInterval={300000} />

Production Deployment

Environment Variables Checklist

• NEXT_PUBLIC_GRAFANA_ENABLED set to true
• NEXT_PUBLIC_GRAFANA_URL points to production Grafana
• NEXT_PUBLIC_GRAFANA_DASHBOARD_UID is correct
• GRAFANA_URL matches public URL
• GRAFANA_SERVICE_TOKEN is production token
• All URLs use HTTPS
• Service token has appropriate permissions
• Token expiration is set

Monitoring

Monitor Grafana integration health:

1. Track iframe load times
2. Monitor proxy API response times
3. Alert on authentication failures
4. Log dashboard access for audit

Support

For issues with:

• Grafana setup: See Grafana Documentation
• Integration bugs: Open issue in repository
• Security concerns: Contact security team

References

• Grafana Embedding Documentation
• Grafana Service Accounts
• Grafana HTTP API