From ef75c0632cb5a1739272a3dd07358a1b619b170a Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Fri, 7 Aug 2026 14:36:04 +0200 Subject: [PATCH 1/5] docs: add Enterprise Commercial License Grafana dashboard page --- src/components/NavigationDocs.jsx | 4 ++ .../enterprise/grafana-dashboard.mdx | 50 +++++++++++++++++++ .../selfhosted/observability/dashboards.mdx | 9 +++- 3 files changed, 61 insertions(+), 2 deletions(-) create mode 100644 src/pages/selfhosted/enterprise/grafana-dashboard.mdx diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index f70cbe212..8a1734972 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -565,6 +565,10 @@ export const docsNavigation = [ title: 'High Availability', href: '/selfhosted/maintenance/scaling/high-availability', }, + { + title: 'Grafana Dashboard', + href: '/selfhosted/enterprise/grafana-dashboard', + }, ], }, { diff --git a/src/pages/selfhosted/enterprise/grafana-dashboard.mdx b/src/pages/selfhosted/enterprise/grafana-dashboard.mdx new file mode 100644 index 000000000..1a632f678 --- /dev/null +++ b/src/pages/selfhosted/enterprise/grafana-dashboard.mdx @@ -0,0 +1,50 @@ +export const description = 'Import and use the Grafana dashboard built for the self-hosted NetBird Enterprise Commercial License management stack.' + +# Enterprise Grafana Dashboard + +The self-hosted NetBird stack with an [Enterprise Commercial License](/selfhosted/enterprise/getting-started) runs more than the management service: NATS carries signalling between instances, and the WebSocket proxy serves browser-based clients. The community [Management dashboard](/selfhosted/observability/dashboards) sees none of that, and when latency spikes on a multi-tenant or [highly available](/selfhosted/maintenance/scaling/high-availability) deployment, the question is usually *which account or peer* is responsible — not just *whether* something is slow. + +The Enterprise dashboard answers both. It is maintained in the `netbirdio/netbird` repository as [`management-enterprise.json`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/observability/grafana/dashboards/management-enterprise.json) and imports directly into Grafana. + +## What it covers + +The dashboard is organized into five rows: + +| Row | What it shows | +| --- | --- | +| General | Connected peers (total, per instance, historical), gRPC `Sync` / `Login` / `GetServerKey` rates, latencies (global and per-account p95), blocked-request rates, store persistence and transaction latency, IdP request rates, HTTP API read/write rates and latencies, PAT usage, and update-channel operations, durations, recreated-channel percentage, and queue length. | +| NATS | Subscriptions and connections per NATS node, message and byte throughput, slow-consumer events, and NATS memory use. NATS carries peer signalling between instances; slow consumers above zero mean a signal node lost its connection and peers lost signalling until it reconnected. | +| Debugging | Top accounts by `Sync` / `Login` requests exceeding the 7-second high-latency threshold, the count of affected accounts, and the top peers by `Sync` log lines — for finding the tenant or peer behind a latency spike or reconnect loop. | +| Network Map | Network map calculation, serialization, and posture check latencies, network map object counts, and map recomputations broken down by the resource that triggered them (policy, group, peer, route, and so on). Map recomputation is the dominant CPU cost during reconnect waves. | +| Browser Client | Active WebSocket proxy connections, traffic by direction, and errors by type. The WebSocket proxy fronts gRPC for browser-based clients, so active connections equals connected web clients. | + +For the individual management metrics behind these panels, see the [Management metrics reference](/selfhosted/observability/management). + +## Prerequisites + +- Prometheus scraping the management `/metrics` endpoint — see [Service endpoints](/selfhosted/observability#service-endpoints). +- For the NATS row: Prometheus scraping the [prometheus-nats-exporter](https://github.com/nats-io/prometheus-nats-exporter), which exposes the `gnatsd_*` metrics the panels query. +- For the per-peer `Sync` ranking in the Debugging row: a Loki datasource with management logs, selected through the `logs_datasource` variable. Without Loki that single panel stays empty; the rest of the dashboard works. + +## Importing the dashboard + +1. In Grafana, go to **Dashboards → New → Import**. +2. Upload [`management-enterprise.json`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/observability/grafana/dashboards/management-enterprise.json) (or paste its contents) and click **Load**. +3. Select your Prometheus datasource (and Loki datasource, if you have one) and complete the import. + +Two panels ship with values specific to the upstream deployment — edit them after import: + +- The **NATS memory consumption** panel filters on hardcoded host names (`nats-1-prod`, `nats-2-prod`). +- The **Highest Syncs by peer key** log panel pins a specific management instance in its Loki query. + +## Dashboard variables + +| Variable | Purpose | +| --- | --- | +| `datasource` | Selects the Prometheus datasource. | +| `logs_datasource` | Selects the Loki datasource for the log-based Debugging panel. | +| `job` | Filters by Prometheus scrape job. | +| `instance` | Filters by management instance when multiple are running. | +| `interval` | Aggregation interval for selected panels (`5m` or `60s`). | + +Unlike the community dashboards, this dashboard does not use `cluster`, `environment`, or `host` variables. diff --git a/src/pages/selfhosted/observability/dashboards.mdx b/src/pages/selfhosted/observability/dashboards.mdx index 3309f9871..f28d04d7d 100644 --- a/src/pages/selfhosted/observability/dashboards.mdx +++ b/src/pages/selfhosted/observability/dashboards.mdx @@ -1,14 +1,15 @@ -export const description = 'Ready-made Grafana dashboards for NetBird Management, Signal, and Relay.' +export const description = 'Ready-made Grafana dashboards for NetBird Management, Signal, Relay, and the Enterprise Commercial License management stack.' # Grafana dashboards -NetBird ships ready-to-use Grafana dashboards for the Management, Signal, and Relay services. They are maintained in the `netbirdio/netbird` repository under [`infrastructure_files/observability/grafana/dashboards`](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/observability/grafana/dashboards) and import directly into Grafana. +NetBird ships ready-to-use Grafana dashboards for the Management, Signal, and Relay services, plus an extended Management dashboard for [Enterprise Commercial License](/selfhosted/enterprise/getting-started) deployments. They are maintained in the `netbirdio/netbird` repository under [`infrastructure_files/observability/grafana/dashboards`](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/observability/grafana/dashboards) and import directly into Grafana. ## Available dashboards | Service | Dashboard JSON | | --- | --- | | Management | [`management.json`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/observability/grafana/dashboards/management.json) | +| Management (Enterprise) | [`management-enterprise.json`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/observability/grafana/dashboards/management-enterprise.json) | | Signal | [`signal.json`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/observability/grafana/dashboards/signal.json) | | Relay | [`relay.json`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/observability/grafana/dashboards/relay.json) | @@ -16,6 +17,10 @@ NetBird ships ready-to-use Grafana dashboards for the Management, Signal, and Re Covers peer-update fan-out, store latency, gRPC `Sync` / `Login` / `GetServerKey` rates and latencies, HTTP API request rates and latencies by endpoint and method, IdP request rates, network-map object counts, and update-channel queue length and operation durations. +### Management (Enterprise) + +An extended Management dashboard for [Enterprise Commercial License](/selfhosted/enterprise/getting-started) deployments, adding NATS, per-account latency debugging, network map, and browser client panels. It has its own prerequisites and variables — see the [Enterprise Grafana Dashboard](/selfhosted/enterprise/grafana-dashboard) page. + ### Signal Covers active peers, peer connection durations, message forwarding throughput and latency, message-forward failures, registration / deregistration rates and failure rates, and gRPC RPC rates and latencies for the Signal service. From 4b6c26228c53931be1a1e4362f764bd62e3a5406 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Fri, 7 Aug 2026 14:48:54 +0200 Subject: [PATCH 2/5] fix: document undefined $host variable in enterprise dashboard --- src/pages/selfhosted/enterprise/grafana-dashboard.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/pages/selfhosted/enterprise/grafana-dashboard.mdx b/src/pages/selfhosted/enterprise/grafana-dashboard.mdx index 1a632f678..a14fd1cc7 100644 --- a/src/pages/selfhosted/enterprise/grafana-dashboard.mdx +++ b/src/pages/selfhosted/enterprise/grafana-dashboard.mdx @@ -14,7 +14,7 @@ The dashboard is organized into five rows: | --- | --- | | General | Connected peers (total, per instance, historical), gRPC `Sync` / `Login` / `GetServerKey` rates, latencies (global and per-account p95), blocked-request rates, store persistence and transaction latency, IdP request rates, HTTP API read/write rates and latencies, PAT usage, and update-channel operations, durations, recreated-channel percentage, and queue length. | | NATS | Subscriptions and connections per NATS node, message and byte throughput, slow-consumer events, and NATS memory use. NATS carries peer signalling between instances; slow consumers above zero mean a signal node lost its connection and peers lost signalling until it reconnected. | -| Debugging | Top accounts by `Sync` / `Login` requests exceeding the 7-second high-latency threshold, the count of affected accounts, and the top peers by `Sync` log lines — for finding the tenant or peer behind a latency spike or reconnect loop. | +| Debugging | Top accounts by `Sync` / `Login` requests exceeding the 7-second high-latency threshold, the count of affected accounts, and the top peers by `Sync` log lines: the tools for finding the tenant or peer behind a latency spike or reconnect loop. | | Network Map | Network map calculation, serialization, and posture check latencies, network map object counts, and map recomputations broken down by the resource that triggered them (policy, group, peer, route, and so on). Map recomputation is the dominant CPU cost during reconnect waves. | | Browser Client | Active WebSocket proxy connections, traffic by direction, and errors by type. The WebSocket proxy fronts gRPC for browser-based clients, so active connections equals connected web clients. | @@ -22,7 +22,7 @@ For the individual management metrics behind these panels, see the [Management m ## Prerequisites -- Prometheus scraping the management `/metrics` endpoint — see [Service endpoints](/selfhosted/observability#service-endpoints). +- Prometheus scraping the management `/metrics` endpoint (see [Service endpoints](/selfhosted/observability#service-endpoints)). - For the NATS row: Prometheus scraping the [prometheus-nats-exporter](https://github.com/nats-io/prometheus-nats-exporter), which exposes the `gnatsd_*` metrics the panels query. - For the per-peer `Sync` ranking in the Debugging row: a Loki datasource with management logs, selected through the `logs_datasource` variable. Without Loki that single panel stays empty; the rest of the dashboard works. @@ -32,10 +32,11 @@ For the individual management metrics behind these panels, see the [Management m 2. Upload [`management-enterprise.json`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/observability/grafana/dashboards/management-enterprise.json) (or paste its contents) and click **Load**. 3. Select your Prometheus datasource (and Loki datasource, if you have one) and complete the import. -Two panels ship with values specific to the upstream deployment — edit them after import: +Some panels ship with values specific to the upstream deployment and need editing after import: - The **NATS memory consumption** panel filters on hardcoded host names (`nats-1-prod`, `nats-2-prod`). - The **Highest Syncs by peer key** log panel pins a specific management instance in its Loki query. +- The **IdP Requests**, **Update Channel operations**, **Update Channel methods p95 Duration**, and per-instance **HTTP request counter** panels filter some of their queries on a `$host` variable the dashboard does not define, so those series stay empty. Add a `host` variable matching your deployment's `host` label, or remove the `host="$host"` filter from those queries. ## Dashboard variables @@ -47,4 +48,4 @@ Two panels ship with values specific to the upstream deployment — edit them af | `instance` | Filters by management instance when multiple are running. | | `interval` | Aggregation interval for selected panels (`5m` or `60s`). | -Unlike the community dashboards, this dashboard does not use `cluster`, `environment`, or `host` variables. +Unlike the community dashboards, this dashboard does not define `cluster`, `environment`, or `host` variables. Some queries still reference `$host` (see the post-import edits above). From 104018406240e44317a1e10d9e52b25cefee6e1b Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Fri, 7 Aug 2026 14:54:23 +0200 Subject: [PATCH 3/5] fix: scope NATS signalling claim to HA deployments --- src/pages/selfhosted/enterprise/grafana-dashboard.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/selfhosted/enterprise/grafana-dashboard.mdx b/src/pages/selfhosted/enterprise/grafana-dashboard.mdx index a14fd1cc7..4ce7dd617 100644 --- a/src/pages/selfhosted/enterprise/grafana-dashboard.mdx +++ b/src/pages/selfhosted/enterprise/grafana-dashboard.mdx @@ -2,7 +2,7 @@ export const description = 'Import and use the Grafana dashboard built for the s # Enterprise Grafana Dashboard -The self-hosted NetBird stack with an [Enterprise Commercial License](/selfhosted/enterprise/getting-started) runs more than the management service: NATS carries signalling between instances, and the WebSocket proxy serves browser-based clients. The community [Management dashboard](/selfhosted/observability/dashboards) sees none of that, and when latency spikes on a multi-tenant or [highly available](/selfhosted/maintenance/scaling/high-availability) deployment, the question is usually *which account or peer* is responsible — not just *whether* something is slow. +The self-hosted NetBird stack with an [Enterprise Commercial License](/selfhosted/enterprise/getting-started) runs more than the management service: NATS carries signalling between instances in [high availability](/selfhosted/maintenance/scaling/high-availability) mode, and the WebSocket proxy serves browser-based clients. The community [Management dashboard](/selfhosted/observability/dashboards) sees none of that, and when latency spikes on a multi-tenant or highly available deployment, the question is usually *which account or peer* is responsible — not just *whether* something is slow. The Enterprise dashboard answers both. It is maintained in the `netbirdio/netbird` repository as [`management-enterprise.json`](https://github.com/netbirdio/netbird/blob/main/infrastructure_files/observability/grafana/dashboards/management-enterprise.json) and imports directly into Grafana. @@ -13,7 +13,7 @@ The dashboard is organized into five rows: | Row | What it shows | | --- | --- | | General | Connected peers (total, per instance, historical), gRPC `Sync` / `Login` / `GetServerKey` rates, latencies (global and per-account p95), blocked-request rates, store persistence and transaction latency, IdP request rates, HTTP API read/write rates and latencies, PAT usage, and update-channel operations, durations, recreated-channel percentage, and queue length. | -| NATS | Subscriptions and connections per NATS node, message and byte throughput, slow-consumer events, and NATS memory use. NATS carries peer signalling between instances; slow consumers above zero mean a signal node lost its connection and peers lost signalling until it reconnected. | +| NATS | Subscriptions and connections per NATS node, message and byte throughput, slow-consumer events, and NATS memory use. In [high availability](/selfhosted/maintenance/scaling/high-availability) deployments NATS carries peer signalling between instances, so slow consumers above zero mean a signal node lost its connection and peers lost signalling until it reconnected. In a single-node stack NATS only carries traffic-flow events, and this row matters less. | | Debugging | Top accounts by `Sync` / `Login` requests exceeding the 7-second high-latency threshold, the count of affected accounts, and the top peers by `Sync` log lines: the tools for finding the tenant or peer behind a latency spike or reconnect loop. | | Network Map | Network map calculation, serialization, and posture check latencies, network map object counts, and map recomputations broken down by the resource that triggered them (policy, group, peer, route, and so on). Map recomputation is the dominant CPU cost during reconnect waves. | | Browser Client | Active WebSocket proxy connections, traffic by direction, and errors by type. The WebSocket proxy fronts gRPC for browser-based clients, so active connections equals connected web clients. | From cf057295214ae161a3e463479581d005ec738b86 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Fri, 7 Aug 2026 15:05:28 +0200 Subject: [PATCH 4/5] fix: drop NATS memory hardcoded-hosts note, fixed upstream --- src/pages/selfhosted/enterprise/grafana-dashboard.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/pages/selfhosted/enterprise/grafana-dashboard.mdx b/src/pages/selfhosted/enterprise/grafana-dashboard.mdx index 4ce7dd617..f9c44a876 100644 --- a/src/pages/selfhosted/enterprise/grafana-dashboard.mdx +++ b/src/pages/selfhosted/enterprise/grafana-dashboard.mdx @@ -34,7 +34,6 @@ For the individual management metrics behind these panels, see the [Management m Some panels ship with values specific to the upstream deployment and need editing after import: -- The **NATS memory consumption** panel filters on hardcoded host names (`nats-1-prod`, `nats-2-prod`). - The **Highest Syncs by peer key** log panel pins a specific management instance in its Loki query. - The **IdP Requests**, **Update Channel operations**, **Update Channel methods p95 Duration**, and per-instance **HTTP request counter** panels filter some of their queries on a `$host` variable the dashboard does not define, so those series stay empty. Add a `host` variable matching your deployment's `host` label, or remove the `host="$host"` filter from those queries. From 5bb258adaea461ef3edbd4163d17278dbd6e087d Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Fri, 7 Aug 2026 15:07:25 +0200 Subject: [PATCH 5/5] fix: scope shared variables table to community dashboards --- src/pages/selfhosted/observability/dashboards.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/selfhosted/observability/dashboards.mdx b/src/pages/selfhosted/observability/dashboards.mdx index f28d04d7d..93304c31e 100644 --- a/src/pages/selfhosted/observability/dashboards.mdx +++ b/src/pages/selfhosted/observability/dashboards.mdx @@ -37,7 +37,7 @@ Covers connected peers (total / active / idle), peer authentication latency, pee ## Dashboard variables -The dashboards expose these template variables: +The Management, Signal, and Relay dashboards expose these template variables: | Variable | Purpose | | --- | --- | @@ -47,7 +47,7 @@ The dashboards expose these template variables: | `job` | Selects a specific NetBird instance when multiple are running. | | `host` | Filters metrics by host. | -Your deployment may use only a subset of these variables; unused ones can be left at the default `All`. +Your deployment may use only a subset of these variables; unused ones can be left at the default `All`. The Enterprise dashboard uses a different variable set — see [its variables table](/selfhosted/enterprise/grafana-dashboard#dashboard-variables). The Management dashboard expects HTTP request metrics to carry an `exported_endpoint` label rather than `endpoint`. If your Prometheus relabeling drops or renames this label, edit the dashboard panel queries accordingly.