Skip to content

updated to reflect changes around event aggregation #800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dmitri-netbird wants to merge 3 commits into
base: main
Choose a base branch
from
Open

updated to reflect changes around event aggregation #800

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
08832dc
updated to reflect changes around event aggregation
dmitri-netbird Jun 17, 2026
2d013ed
linter wasn't happy with a placeholder for the groping interval
dmitri-netbird Jun 17, 2026
4a5ed5d
missing coma
dmitri-netbird Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions src/pages/manage/activity/traffic-events-logging.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -115,6 +115,11 @@ in one TCP session, but the routing peer blocked all attempts.
E.g., `nc -v crm.netbird.cloud 443`.
</Note>

## 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 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.


## Enabling Traffic Events Logging

Traffic events logging feature is disabled by default. To enable it on the NetBird dashboard, navigate to `Settings > Networks`.
Expand Down Expand Up @@ -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.

@coderabbitai coderabbitai Bot Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Align the ICMP schema between the field list and the JSON sample.

The field reference now documents only ICMP Type, but the sample payload still includes icmp_code. That presents two different contracts for the same event shape.

Suggested alignment (if ICMP code is no longer part of the model) 
-    "icmp_code": 0,
     "icmp_type": 0,

Also applies to: 240-244

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/pages/manage/activity/traffic-events-logging.mdx` at line 184, The field
reference documentation at line 184 lists only ICMP Type, but the JSON sample
payload at lines 240-244 includes both icmp_type and icmp_code fields. Align
these two sections by either adding ICMP Code to the field reference list in the
documentation, or remove the icmp_code field from the JSON sample payload to
match the field list. Ensure both the field reference and the sample payload
document the same event schema to provide a consistent contract.

* **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.

Expand Down Expand Up @@ -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"
Expand Down
Loading