Client Metrics
Updated
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.
Metrics push is disabled by default. When enabled, clients periodically push metrics to a collection server. Clients always collect these metrics locally and include them in debug bundles regardless of this setting. The setting only controls whether the metrics are pushed.
What is collected
- Connection stages: Time taken for each stage of a peer connection, covering signaling, connection establishment, and WireGuard handshake.
- Sync duration: How long it takes to process management server sync messages, including individual processing phases.
- 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.
The set of collected metrics may be extended in future releases to cover additional performance and connectivity data points.
Enabling via the dashboard
- Navigate to Settings > Metrics.
- Toggle Share performance metrics to enable or disable metrics push for all peers in your account.
Changing the toggle requires the Owner or Admin role. For other roles the toggle is disabled. Connected clients apply the change within seconds through a management update; offline clients pick it up on their next login. Enabling or disabling the setting is recorded in the account activity log.
Controlling metrics push from the dashboard requires client version 0.74.0 or later. Older clients ignore the
account setting and only push metrics when NB_METRICS_PUSH_ENABLED=true is set (supported since version 0.67.0).
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 |
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 push for that client.
You can additionally set NB_METRICS_INTERVAL to a duration value (e.g., 30m, 1h) to override how often metrics
are pushed.