From 07e679e857e6afc135daca607d29e79170ab85f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zolt=C3=A1n=20Papp?= <zoltan.pmail@gmail.com>
Date: Tue, 14 Apr 2026 17:38:53 +0200
Subject: [PATCH] Add client metrics documentation

Add docs page for the new client metrics push feature covering what
is collected, how to enable via dashboard, and env var override.
---
 src/components/NavigationDocs.jsx   |  4 +++
 src/pages/manage/client-metrics.mdx | 42 +++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 src/pages/manage/client-metrics.mdx

diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx
index 3a88d357..be2d2d30 100644
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -438,6 +438,10 @@ export const docsNavigation = [
           },
           { title: 'Auto Update', href: '/manage/peers/auto-update' },
           { title: 'Lazy Connections', href: '/manage/peers/lazy-connection' },
+          {
+            title: 'Client Metrics',
+            href: '/manage/client-metrics',
+          },
           {
             title: 'Notifications',
             href: '/manage/settings/notifications',
diff --git a/src/pages/manage/client-metrics.mdx b/src/pages/manage/client-metrics.mdx
new file mode 100644
index 00000000..8fa77b18
--- /dev/null
+++ b/src/pages/manage/client-metrics.mdx
@@ -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>