From 08832dc0c62a2c3cc29956a4a478c1c2d3cc70df Mon Sep 17 00:00:00 2001 From: Dmitri Dolguikh Date: Wed, 17 Jun 2026 10:15:41 +0200 Subject: [PATCH 1/3] updated to reflect changes around event aggregation Signed-off-by: Dmitri Dolguikh --- .../activity/traffic-events-logging.mdx | 25 +++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/src/pages/manage/activity/traffic-events-logging.mdx b/src/pages/manage/activity/traffic-events-logging.mdx index d690ae6be..52f1b26db 100644 --- a/src/pages/manage/activity/traffic-events-logging.mdx +++ b/src/pages/manage/activity/traffic-events-logging.mdx @@ -37,7 +37,7 @@ NetBird would log the blocked event on the peer that refused the connection. #### Successful P2P Connection Events -NetBird helps you better understand connection flows by correlating related events and presenting them in a clear, organized manner. +NetBird helps you better understand connection flows by aggregating related events and presenting them in a clear, organized manner. For example, in a successful peer-to-peer connection scenario, a user initiates a connection from the peer `Alice` to the peer `server`. This is illustrated in the screenshot below. @@ -115,6 +115,11 @@ in one TCP session, but the routing peer blocked all attempts. E.g., `nc -v crm.netbird.cloud 443`. +## Event Grouping +All connections from a peer are grouped by protocol, destination address, destination port, and icmp type (for icmp only) over a time interval of <>. +During this time interval the total number of bytes and packets sent and received and the number of traffic events of each type is collected for each group of connections. + + ## Enabling Traffic Events Logging Traffic events logging feature is disabled by default. To enable it on the NetBird dashboard, navigate to `Settings > Networks`. @@ -167,16 +172,19 @@ For detailed instructions on supported integrations and how to set them up, refe When enabled, a NetBird peer will record metadata for each network flow that it participates in. The data collected by peers includes: -* **Timestamp**: When the flow started and ended. +* **WindowStart**: When the grouping window started. +* **WindowEnd**: When the grouping window ended. * **Flow ID**: A unique identifier for the traffic event flow. -* **Type**: The type of traffic event, such as Start, End, or Blocked. +* **NumOfStarts**: The number of Start events in the group. +* **NumOfEnds**: The number of Stop events in the group +* **NumOfDrops**: The number of Drop events in the group * **Source and Destination IP Addresses**: The IP of the peer (source) and the IP of the remote endpoint (destination). For peer-to-peer traffic, these will be the NetBird network IPs (e.g. 100.x.x.x addresses of each peer). For traffic to an external resource (like a private server or subnet), the destination might be an IP in that remote network. * **Source and Destination Ports**: The network ports used by the connection (for TCP/UDP flows). -* **ICMP Code and Type**: For ICMP traffic, the ICMP code and type. +* **ICMP Type**: The ICMP type for grouped ICMP traffic. * **Protocol**: The protocol of the traffic, such as TCP, UDP, or ICMP. * **Direction**: Whether the flow was inbound or outbound. This takes into consideration the perspective of the **peer reporting the traffic** and the NetBird interface. -* **Volume of Data**: The amount of data transferred, measured in number of packets and bytes sent/received for the duration of the flow. +* **Volume of Data**: The amount of data transferred, measured in number of packets and bytes sent/received for the duration of the grouping window. * **Resource ID**: Network route or Networks resource ID that the flow is associated with. This is useful for identifying the routing configuration that allowed the flow. DNS route information is **available only** on the routing client. * **Rule ID**: The ID of the policy that allowed the flow. This is useful for identifying the access control policy that allowed the flow. This information is **available only** on the receiving side of the traffic. @@ -229,10 +237,13 @@ In addition to the data collected by the peers, the NetBird API provides additio "os": "Darwin", "type": "PEER" }, - "timestamp": "2025-03-22T20:26:16.937522Z", + "window_start": "2025-03-22T20:26:16.937522Z", + "window_end": "2025-03-22T20:30:17.257891Z", + "num_of_starts": 1, + "num_of_ends": 0, + "num_of_drops": 0 "tx_bytes": 64, "tx_packets": 1, - "type": "TYPE_START", "user_email": "john@example.com", "user_id": "google-oauth2|xyz0123", "user_name": "John Doe" From 2d013ed960e0849eee26699c77bd49ed9b947ae6 Mon Sep 17 00:00:00 2001 From: Dmitri Dolguikh Date: Wed, 17 Jun 2026 10:25:00 +0200 Subject: [PATCH 2/3] linter wasn't happy with a placeholder for the groping interval Signed-off-by: Dmitri Dolguikh --- src/pages/manage/activity/traffic-events-logging.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/manage/activity/traffic-events-logging.mdx b/src/pages/manage/activity/traffic-events-logging.mdx index 52f1b26db..cd78962a0 100644 --- a/src/pages/manage/activity/traffic-events-logging.mdx +++ b/src/pages/manage/activity/traffic-events-logging.mdx @@ -116,7 +116,7 @@ in one TCP session, but the routing peer blocked all attempts. ## Event Grouping -All connections from a peer are grouped by protocol, destination address, destination port, and icmp type (for icmp only) over a time interval of <>. +All connections from a peer are grouped by protocol, destination address, destination port, and icmp type (for icmp only) over a time interval of 5 minutes. During this time interval the total number of bytes and packets sent and received and the number of traffic events of each type is collected for each group of connections. From 4a5ed5d3c94c05ca83541cd87e11e3b23a0e622e Mon Sep 17 00:00:00 2001 From: Dmitri Dolguikh Date: Thu, 18 Jun 2026 10:41:37 +0200 Subject: [PATCH 3/3] missing coma Signed-off-by: Dmitri Dolguikh --- src/pages/manage/activity/traffic-events-logging.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/manage/activity/traffic-events-logging.mdx b/src/pages/manage/activity/traffic-events-logging.mdx index cd78962a0..3c4a75fe8 100644 --- a/src/pages/manage/activity/traffic-events-logging.mdx +++ b/src/pages/manage/activity/traffic-events-logging.mdx @@ -241,7 +241,7 @@ In addition to the data collected by the peers, the NetBird API provides additio "window_end": "2025-03-22T20:30:17.257891Z", "num_of_starts": 1, "num_of_ends": 0, - "num_of_drops": 0 + "num_of_drops": 0, "tx_bytes": 64, "tx_packets": 1, "user_email": "john@example.com",