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>