Add client metrics documentation (#701)

Add docs page for the new client metrics push feature covering what is collected, how to enable via dashboard, and env var override.
2026-09-28 17:59:05 +02:00 · 2026-07-01 20:09:21 +02:00
parent 569aeafd01
commit f122fcf827
2 changed files with 46 additions and 0 deletions
@@ -0,0 +1,42 @@
+import {Note} from "@/components/mdx";
+
+# Client Metrics
+
+Client metrics allow you to collect performance data from your NetBird clients, such as connection timing,
+sync duration, and login latency. This data helps identify connectivity issues and optimize your deployment.
+
+When enabled, clients periodically push metrics to a collection server.
+
+## What is collected
+
+- **Connection stages** — Time taken for each stage of a peer connection: signaling, connection establishment, and WireGuard handshake.
+- **Sync duration** — How long it takes to process management server sync messages.
+- **Login duration** — How long the login to the management server takes, including success or failure status.
+
+Each metric includes metadata such as the client version, operating system, architecture, and deployment type (cloud or self-hosted). Peer identifiers are hashed before transmission.
+
+<Note>
+    The set of collected metrics may be extended in future releases to cover additional performance and connectivity data points.
+</Note>
+
+## Enabling via the dashboard
+
+1. Navigate to **Settings** > **Metrics**.
+2. Toggle **Share performance metrics** to enable or disable metrics push for all peers in your account.
+
+When enabled, all connected clients will start pushing metrics on their next sync with the management server.
+
+## Environment variable override
+
+The `NB_METRICS_PUSH_ENABLED` environment variable on the client takes precedence over the dashboard setting:
+
+| Value | Behavior |
+|-------|----------|
+| `true` | Metrics push is always enabled, regardless of the dashboard setting |
+| `false` | Metrics push is always disabled, regardless of the dashboard setting |
+| *(unset)* | The dashboard setting controls whether metrics push is enabled |
+
+<Note>
+    When `NB_METRICS_PUSH_ENABLED` is explicitly set on the client, changes to the dashboard toggle will have no effect on that client.
+    Setting it to `false` is an explicit opt-out from metrics collection for that client.
+</Note>