Grafana dashboards for monitoring OpenCloud with the PLG stack (Prometheus + Loki + Grafana).
| Dashboard | UID | Datasource | Description | Docs |
|---|---|---|---|---|
| Overview | opencloud-overview |
Prometheus | Quick health check (start here) | 📖 |
| Logs | opencloud-logs |
Loki | Service/Component/Level filter | 📖 |
| Proxy | opencloud-proxy |
Loki | HTTP access logs, traffic analysis | 📖 |
| Uploads | opencloud-uploads |
Prometheus | File uploads, antivirus, processing | 📖 |
| Requests | opencloud-requests |
Prometheus | Performance analysis, latency | 📖 |
| User Activity | opencloud-user-activity |
Loki | Authentication, audit trail, user logs | 📖 |
| Activitylog Debug | activitylog-debug |
Loki | Event debugging (for upstream issues) | 📖 |
Downloaded from Grafana.com during deployment:
| Dashboard | UID | Source | Description | Docs |
|---|---|---|---|---|
| Node Exporter Full | node-exporter-full |
#1860 | Linux server metrics | 📖 |
| Prometheus Stats | prometheus-stats |
#3662 | Prometheus self-monitoring | 📖 |
┌─────────────────────┐
│ OpenCloud Overview │ ← Start here
│ (Prometheus) │
└──────────┬──────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Requests │ │ Uploads │ │ Logs │
│ (Prometheus)│ │ (Prometheus)│ │ (Loki) │
└─────────────┘ └─────────────┘ └──────┬──────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Proxy │ │ Activitylog │ │ (filter by │
│ (Loki) │ │ (Loki) │ │ component) │
└─────────────┘ └─────────────┘ └─────────────┘
src/ # Dashboard source (TypeScript)
├── shared.ts # Datasources, query helpers, thresholds
├── activitylog.ts # Activitylog Debug dashboard
├── opencloud-overview.ts # Overview dashboard
├── opencloud-logs.ts # Logs dashboard
├── opencloud-proxy.ts # Proxy dashboard
├── opencloud-uploads.ts # Uploads dashboard
├── opencloud-requests.ts # Requests dashboard
└── opencloud-user-activity.ts # User Activity dashboard
docs/
└── dashboards/ # Dashboard documentation
├── opencloud-overview.md
├── opencloud-logs.md
├── opencloud-proxy.md
├── opencloud-uploads.md
├── opencloud-requests.md
├── opencloud-user-activity.md
├── activitylog.md
├── node-exporter.md # Docs for external dashboard
└── prometheus-stats.md # Docs for external dashboard
grafana/
└── provisioning/
├── dashboards/
│ ├── dashboards.yml # Provisioning config
│ └── *.json # Generated by `bun run build` (gitignored)
└── datasources/
└── datasources.yml # Prometheus + Loki
Panel IDs follow a row-based numbering scheme:
| Element | IDs | Example |
|---|---|---|
| Row panels | 100, 200, 300... | Row 200 = second section |
| Panels in row | +10, +20, +30... | Panel 230 = 3rd panel in Row 200 |
| No rows (Overview) | 10, 20, 30... | Flat structure |
Benefits: Clear hierarchy, room for growth (insert 115 between 110/120), easy debugging.
Dashboards are written in TypeScript using the Grafana Foundation SDK. Each src/*.ts file defines a dashboard with typed builders and generates JSON via console.log(JSON.stringify(dashboard.build())). The generated JSON is not committed — it is built during deployment and in CI.
| Resource | Link |
|---|---|
| Documentation | grafana.com/docs/.../foundation-sdk |
| API Reference | grafana.github.io/grafana-foundation-sdk |
| GitHub | grafana/grafana-foundation-sdk |
| npm | @grafana/grafana-foundation-sdk |
| SDK Version | ~11.6.0-cogv0.0.x (matches Grafana 11.6) |
Key patterns used:
| Builder | Import | Used for |
|---|---|---|
DashboardBuilder |
dashboard |
Dashboard metadata, variables, rows |
PanelBuilder as StatBuilder |
stat |
Single-value stat panels |
PanelBuilder as TimeseriesBuilder |
timeseries |
Time series charts |
PanelBuilder as GaugeBuilder |
gauge |
Gauge panels |
PanelBuilder as LogsBuilder |
logs |
Log stream panels |
PanelBuilder as PiechartBuilder |
piechart |
Pie charts |
PanelBuilder as TableBuilder |
table |
Table panels |
PanelBuilder as BarGaugeBuilder |
bargauge |
Bar gauge panels |
PanelBuilder as HeatmapBuilder |
heatmap |
Heatmap panels |
DataqueryBuilder |
prometheus, loki |
Query definitions |
src/shared.ts provides reusable helpers: datasource refs, query factories (promQuery, lokiQuery), threshold factories (greenYellowRed, etc.), and override helpers (colorOverride, regexpColorOverride).
- Bun runtime (optional — CI and deployment install Bun automatically)
bun install
bun run build # Build all dashboards
bun run typecheck # Type check onlyIndividual dashboards:
bun run build:opencloud-overview
bun run build:opencloud-logs
# etc.- Edit TypeScript source in
src/ - Commit and push (only TypeScript, JSON is gitignored)
- CI validates (typecheck + build)
- Deployment builds JSON on the server with Bun
The validate-dashboards.yml workflow runs on push/PR to main when src/, package.json, or tsconfig.json change:
- Type check —
bun run typecheck(catches type errors, wrong builder methods) - Build —
bun run build(verifies all 7 dashboards generate valid JSON)
A deployment workflow clones this repo, runs bun install --frozen-lockfile && bun run build, and copies the generated JSON to Grafana's provisioning directory.
These dashboards are designed for use with:
- OpenCloud metrics (Prometheus)
- OpenCloud logs (Loki via Grafana Alloy)
- Grafana 10.x or 11.x
- Prometheus datasource (UID:
prometheus) - Loki datasource (UID:
loki)
bun install && bun run buildThen copy grafana/provisioning/ to your Grafana provisioning directory. Or import individual JSON files via Grafana UI → Dashboards → Import.
External dashboards (Node Exporter, Prometheus Stats) are downloaded from Grafana.com during deployment and processed to set stable UIDs, replace datasource variables, and adapt label names for Alloy.
- OpenCloud - The cloud platform
- OpenCloud Compose - Docker Compose deployment
MIT