docs: traffic events streaming fields, delivery, unrecorded traffic, audit events and peer IP allocation (#1010)

* docs: traffic events streaming fields, delivery, unrecorded traffic, audit events and peer IP allocation

* docs: scope traffic event retries to the save and list client-side data loss

* docs: scope traffic event retry guarantee to server-side steps

Reverts a2f549b4's client-side loss list and drops the restart sentence;
the retry and delayed-not-dropped claims now cover only events that have
reached the servers.

src/pages/about-netbird/how-netbird-works.mdx

@@ -44,6 +44,8 @@ After installation, NetBird client requires login that can be done through Ident
 * **Keeping the network map.** The Management service stores information about all the registered peers including WireGuard public key that was sent during the registration process.
 * **Managing private IP addresses.** Each peer receives a unique private IP with which it can be identified in the network.
 We use [Carrier Grade NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) address space with an allocated address block <em>100.64.0.0/10</em>.
+Each account gets its own range inside this block, a randomly chosen /16 by default, and each new peer receives a randomly chosen free address from it.
+When a peer is deleted, its address is released immediately and can be assigned to a later peer; there is no holding period.
 * **Synchronizing network changes to peers.** The Management Service keeps a control channel open to each peer sending network updates.
 Whenever a new peer joins the network, all other peers that are authorized to connect to it receive an update.
 After that, they are able to establish a connection to the new peer.

src/pages/manage/activity/event-streaming/index.mdx

@@ -23,4 +23,19 @@ supported third-party platforms. To get started, select one of the following int
 - [Amazon Data Firehose](/manage/activity/event-streaming/amazon-firehose)
 - [SentinelOne Data Lake](/manage/activity/event-streaming/sentinelone-data-lake)
 - [Generic HTTP](/manage/activity/event-streaming/generic-http)
-- [Wazuh](/manage/activity/event-streaming/wazuh)
+- [Wazuh](/manage/activity/event-streaming/wazuh)
+
+## Delivery
+
+NetBird streams each audit event and traffic event after saving it, so an event that fails to stream is not lost: it remains in the [audit events log](/manage/activity) or the [traffic events](/manage/activity/traffic-events-logging) store. When the destination is unreachable or rejects an event, Datadog and Generic HTTP behave differently:
+
+- **Datadog**: one delivery attempt per event. A failed delivery is not retried.
+- **Generic HTTP**: a failed delivery is retried twice, after 1 and then 2 seconds, before the event is dropped (three attempts in total by default).
+
+Creating, updating, and deleting a stream destination are recorded in the audit events log as `Integration created`, `Integration updated`, and `Integration deleted`. Updating includes enabling and disabling the destination.
+
+Changes to a stream destination take up to five minutes to apply, because NetBird caches the destination's settings. After you disable or delete a destination, audit and traffic events can keep arriving there for up to five minutes, including the event that records the change. After you enable it again, events can take the same time to resume. In self-hosted Enterprise deployments, this interval is set by `NB_EVENT_STREAMING_CACHE_TTL` on the management server and the enricher service.
+
+NetBird removes any `name` or `email` key from `meta` before streaming an event. For many audit events, such as group, policy, and peer changes, `name` is where the object's name is, so look it up in the audit events log using `target_id`.
+
+For the fields carried by streamed traffic events, see [Streamed event fields](/manage/activity/traffic-events-logging#streamed-event-fields).

src/pages/manage/activity/event-streaming/wazuh.mdx

@@ -93,7 +93,7 @@ NetBird emits **two distinct event shapes** through the same integration. Both a
 - **`ID` may be a number or a string** (test events use a string identifier; real audit events use a numeric ID). Wazuh normalises both to strings in the indexed `data.nb.ID`, so KQL queries don't need to handle the mixed type.
 - **`Message`** is the most reliable field to pivot rules on; it's a stable English phrase like "peer added" or "policy created".
 - **`reference`** is the canonical URL into NetBird's activity log; useful as a click-through pivot from a Wazuh alert back to the source event.
-- **`meta` is event-type-specific.** Peer events carry `meta.name`, setup-key events carry `meta.type`, integration events carry `meta.platform`. Treat unknown keys as opaque.
+- **`meta` is event-type-specific.** Peer events carry `meta.fqdn` and `meta.ip`, setup-key events carry `meta.type`, integration events carry `meta.platform`. Any `name` or `email` key is removed before streaming. Treat unknown keys as opaque.
 
 ### Traffic events
 

src/pages/manage/activity/index.mdx

@@ -104,6 +104,14 @@ The current version of NetBird tracks a wide range of network changes that occur
     - Integration updated
     - Integration deleted
 
+  - **Traffic Events Logging Management:**
+    - Network traffic logging enabled
+    - Network traffic logging disabled
+    - Network traffic packet counting enabled
+    - Network traffic packet counting disabled
+    - Network traffic group added
+    - Network traffic group removed
+
   - **Other Events:** 
     - Transferred owner role
     - Posture check created

src/pages/manage/activity/traffic-events-logging.mdx

@@ -153,12 +153,16 @@ choose the groups you want to include, and click `Save Groups`.
     <img src="/docs-static/img/manage/activity/traffic-events-logging/traffic-events-groups-logging-settings.png" alt="traffic-events-groups-logging-settings" className="imagewrapper-big"/>
 </p>
 
+Changes to these settings, including the group scope, are pushed to connected peers and take effect without restarting the NetBird client. Every change is also recorded in the [audit events log](/manage/activity).
+
 ## Log Retention
 
 While in experimental mode, logs are retained for **seven days**.
 Additionally, the current API returns a maximum of **50,000 flow records**.
 This limit may change.
 
+In self-hosted Enterprise deployments, the retention period is set by `NB_PERSISTENCE_RETENTION_PERIOD` on the enricher service. The installer sets it to `168h` (seven days).
+
 ## Report rate
 Aggregated flows might take up to **ten minutes** to become available through the API and Dashboard. An end count for some TCP connections can appear in a later window, depending on OS settings and connection termination.
 
@@ -170,6 +174,27 @@ enhancing your ability to detect and respond to security events.
 
 For detailed instructions on supported integrations and how to set them up, refer to the [integrations guide](/manage/activity/event-streaming).
 
+### Streamed event fields
+
+A streamed traffic event uses the same envelope as a streamed audit event: an event ID, a timestamp, and a message. Clients from v0.75 send aggregated events, whose message is always `TYPE_UNKNOWN`, so read activity from the `num_of_*` counts instead. The initiator and target fields are empty, and the reference field is empty or, for Datadog, omitted. Envelope field names depend on the integration: Datadog uses `id` and `timestamp`, Generic HTTP uses `ID` and `Timestamp`. The flow details are in `meta`, under the same keys for every integration unless you set a custom Generic HTTP body template:
+
+* **User**: `user_id`, the ID of the user associated with the source peer.
+* **Flow**: `flow_id`, `reporter_id` (the peer that reported the event), `protocol`, `direction`, `policy_id`, `policy_name`, `icmp_type`, and `icmp_code`.
+* **Source and destination**: `source_id`, `source_name`, `source_addr`, `source_dns_label`, `source_connection_ip`, `source_geo_city`, and `source_geo_country`, with the same set of `destination_*` fields.
+* **Volume**: `rx_bytes`, `rx_packets`, `tx_bytes`, and `tx_packets`.
+* **Counts**: `num_of_starts`, `num_of_ends`, and `num_of_drops`.
+* **Timing**: `received_timestamp`, the time the event reached the NetBird servers.
+
+Compared with API responses, streamed events do not include the user's name or email, the aggregation window start and end, or the operating system of the source and destination. `user_id` is empty when the source peer has no associated user, such as a peer registered with a [setup key](/manage/peers/register-machines-using-setup-keys), and when the source is not a peer.
+
+### Streaming delivery
+
+Each traffic event is saved to the traffic events store before it is streamed, so an event that fails to stream is still visible in the Dashboard and API. The NetBird client resends each event until the NetBird servers acknowledge it. Once an event reaches the servers, every step up to saving it is retried: the servers acknowledge an event only after queueing it, and remove it from the queue only after saving it. If server processing falls behind, events wait in the queue and arrive late rather than being dropped.
+
+In rare cases, such as a server restart while an event is being processed, the same event can be streamed twice. Deduplicate on the event ID.
+
+Changes to a stream destination take up to five minutes to apply, and what happens when the destination is unreachable depends on the integration; see [Delivery](/manage/activity/event-streaming#delivery).
+
 ## Traffic Events Data
 
 When enabled, a NetBird peer will record metadata for each network flow that it participates in. The data collected by peers includes:
@@ -192,7 +217,7 @@ In addition to the data collected by the peers, the NetBird API provides additio
 * **Peer ID**: The unique identifier of the peer.
 * **Resource name**: The name of the resource or network route.
 * **Policy Name**: The name of the policy that allowed the flow.
-* **User ID, name, and email**: The name and email of the user associated with the source peer.
+* **User ID, name, and email**: The name and email of the user associated with the source peer. The API looks these up when you query it; [streamed events](#streamed-event-fields) carry the user ID only.
 * **Reporter ID**: The unique identifier of the peer that reported the traffic event.
 * **Received timestamp**: The timestamp when the event was received by the NetBird servers.
 
@@ -352,6 +377,14 @@ On Linux, you can force a routing peer into userspace mode with three [environme
 sudo netbird service reconfigure --service-env NB_WG_KERNEL_DISABLED=true,NB_FORCE_USERSPACE_FIREWALL=true,NB_FORCE_USERSPACE_ROUTER=true
 ```
 
+### Traffic that is not recorded
+
+Some traffic never produces a traffic event, whatever the peer mode:
+
+* **DNS queries over UDP.** The NetBird client does not record UDP traffic to port `53`, or to ports `5353` and `22054`, which the NetBird DNS forwarder uses on routing peers. This also applies to other UDP traffic on these ports, such as mDNS. DNS over TCP is recorded as an ordinary flow.
+* **Traffic through an exit node.** Flows matched to an exit node route (`0.0.0.0/0`) are not recorded, on the client or on the exit node. Traffic to a destination covered by a more specific route or Networks resource is still recorded.
+* **Access withdrawn by a failed posture check.** When a peer fails a [posture check](/manage/access-control/posture-checks), the policy stops applying and the connection between the peers is removed. No traffic reaches either peer's firewall, so there is nothing to record as allowed or blocked.
+
 ## Conclusion
 Traffic events logging provides a powerful tool for monitoring and analyzing network traffic across your infrastructure.
 Enabling this feature can provide valuable insights into network activity, enhance security measures, and improve operational efficiency.