From 806edafa4414eaf0a9b6629bf46ebfad29437f2b Mon Sep 17 00:00:00 2001 From: mereta Date: Thu, 27 Aug 2026 16:42:07 +0100 Subject: [PATCH] fix(docs): Update docs Signed-off-by: mereta --- docs/02-Installation/03-Config.md | 2 +- docs/03-Metrics/02-hubble_metrics.md | 9 ++++-- docs/03-Metrics/modes/advanced.md | 4 +++ docs/03-Metrics/modes/basic.md | 33 ++++++++++++++++----- docs/03-Metrics/plugins/Linux/linuxutil.md | 9 ++++++ docs/03-Metrics/plugins/Linux/tcpretrans.md | 4 +++ docs/03-Metrics/plugins/readme.md | 10 +++++-- 7 files changed, 58 insertions(+), 13 deletions(-) diff --git a/docs/02-Installation/03-Config.md b/docs/02-Installation/03-Config.md index 177dd661ec..9fafd15aae 100644 --- a/docs/02-Installation/03-Config.md +++ b/docs/02-Installation/03-Config.md @@ -45,7 +45,7 @@ Apply to both Agent and Operator. ## Agent Configuration * `logLevel`: Define the level of logs to store. -* `enabledPlugin_linux`: List of enabled plugins. +* `enabledPlugin_linux`: List of enabled plugins. See the [plugin list](../03-Metrics/plugins/readme.md) for valid names and operating-system availability. * `metricsInterval`: Interval for gathering metrics (in seconds). (@deprecated, use `metricsIntervalDuration` instead) * `metricsIntervalDuration`: Interval for gathering metrics (in `time.Duration`). * `enablePodLevel`: Enables gathering of advanced pod-level metrics, attaching pods' metadata to Retina's metrics. diff --git a/docs/03-Metrics/02-hubble_metrics.md b/docs/03-Metrics/02-hubble_metrics.md index 649c8fd8c4..52aea5cac9 100644 --- a/docs/03-Metrics/02-hubble_metrics.md +++ b/docs/03-Metrics/02-hubble_metrics.md @@ -40,8 +40,13 @@ The table below outlines the different metrics generated. | **networkobservability_dns_request_count** | Total DNS request count | | ✅ | ❌ | | **networkobservability_dns_response_count** | Total DNS response count | | ✅ | ❌ | | **networkobservability_windows_hns_stats** | Windows HNS statistics (packets sent/received) | `direction` | ❌ | ✅ | -| **networkobservability_node_connectivity_status** | Connectivity status between nodes (1=connected, 0=not) | `source_node_name`, `target_node_name` | ✅ | ✅ | -| **networkobservability_node_connectivity_latency_seconds** | Latency in seconds between nodes | `source_node_name`, `target_node_name` | ✅ | ✅ | +| **networkobservability_node_connectivity_status** | Deprecated; registered but not populated | `source_node_name`, `target_node_name` | ❌ | ❌ | +| **networkobservability_node_connectivity_latency_seconds** | Deprecated; registered but not populated | `source_node_name`, `target_node_name` | ❌ | ❌ | + +> **Note:** Linux `interface_stats` may expose no samples because it includes +> only non-zero `ethtool -S` counters containing `err` or `drop`. +> The deprecated node-connectivity collectors remain registered for +> compatibility but expose no metric series. ### Pod-Level Metrics (Hubble Metrics) diff --git a/docs/03-Metrics/modes/advanced.md b/docs/03-Metrics/modes/advanced.md index 268f9ea6ae..98226f9582 100644 --- a/docs/03-Metrics/modes/advanced.md +++ b/docs/03-Metrics/modes/advanced.md @@ -158,6 +158,10 @@ Metrics enabled when `tcpretrans` plugin is enabled (see [Metrics Configuration] | ---------------------- | -------------------------------------------------------- | -------------- | | `adv_tcpretrans_count` | ***Advanced/Pod-Level***: TCP retransmitted packet count | context labels | +> **Note:** This differs from +> node-wide `linuxutil` counters such as +> `tcp_connection_stats{statistic_name="TCPLostRetransmit"}`. + #### Label Values See [Context Labels](#context-labels). diff --git a/docs/03-Metrics/modes/basic.md b/docs/03-Metrics/modes/basic.md index 7674fbe506..d0719d0809 100644 --- a/docs/03-Metrics/modes/basic.md +++ b/docs/03-Metrics/modes/basic.md @@ -93,10 +93,14 @@ Possible values for TCP `state`: Possible values for `statistic_name` (for metric `tcp_connection_stats`): - `TCPTimeouts` -- `TCPTSReorder` -- `ResetCount` +- `TCPLossProbes` +- `TCPLostRetransmit` - and many others (full list [here](../plugins/Linux/linuxutil.md#label-values-for-tcp_connection_stats)) +> **Note:** Linux emits only non-zero values from the current `linuxutil` +> allowlist. For example, `TCPTSReorder` may exist in `/proc/net/netstat`, but +> it is not currently emitted. + Possible values for `statistic_name` (for metric `ip_connection_stats`): - `InNoECTPkts` @@ -120,6 +124,12 @@ Possible values for `statistic_name` (for metric `interface_stats`): - `tx_send_full` - and many others (as seen by running `ethtool -S ` on the Node) +> **Note:** For `interface_stats` only, Retina exports an `ethtool -S` counter +> when its value is greater than zero and its name contains `err` or `drop`. +> Retina adds matching values from all supported interfaces together and sets +> `interface_name="all_interfaces"`. If no counter matches both conditions, +> the metric has no series. + ### Plugin: `dns` (Linux) Metrics enabled when `dns` plugin is enabled (see [Metrics Configuration](../configuration.md)). @@ -141,14 +151,15 @@ Metrics enabled when `conntrack` plugin is enabled and `enableConntrackMetrics` | `conntrack_bytes_rx` | Total bytes received tracked by conntrack | | | `conntrack_total_connections`| Total number of tracked connections | | -### Node Connectivity Metrics (Linux/Windows) +### Node Connectivity Metrics (Deprecated) -These metrics are available when node connectivity monitoring is enabled. +| Metric Name | Description | Extra Labels | +| ----------------------------------- | --------------------------------------------- | -------------------------------------- | +| `node_connectivity_status` | Deprecated connectivity status between nodes | `source_node_name`, `target_node_name` | +| `node_connectivity_latency_seconds` | Deprecated latency in seconds between nodes | `source_node_name`, `target_node_name` | -| Metric Name | Description | Extra Labels | -| ------------------------------------ | ----------------------------------------------------- | ------------------------------------ | -| `node_connectivity_status` | Connectivity status between nodes (1=connected, 0=not)| `source_node_name`, `target_node_name` | -| `node_connectivity_latency_seconds` | Latency in seconds between nodes | `source_node_name`, `target_node_name` | +> **Note:** These collectors remain registered for compatibility, but the +> current agent does not populate them, so they expose no metric series. ### Plugin: `hnsstats` (Windows) @@ -187,6 +198,12 @@ Possible values for `statistic_name` (for metric `tcp_connection_stats`): - `TimedOutCount` - `TimeWaitExpiredCount` +> **Note:** `ResetCount` appears as +> `networkobservability_tcp_connection_stats{statistic_name="ResetCount"}`. +> These connection statistics are inbound node-level gauges without a +> `direction` label. `tcp_flag_gauges` is separate and includes both ingress +> and egress VFP packet counters. + Possible values for TCP `flag`: - `SYN` diff --git a/docs/03-Metrics/plugins/Linux/linuxutil.md b/docs/03-Metrics/plugins/Linux/linuxutil.md index f70f7d5618..337436c714 100644 --- a/docs/03-Metrics/plugins/Linux/linuxutil.md +++ b/docs/03-Metrics/plugins/Linux/linuxutil.md @@ -54,6 +54,10 @@ type NetstatOpts struct { These are initialized in the linuxutil.go file. +> **Note:** The current runtime sets `errOrDropKeysOnly: true` and +> `addZeroVal: false`. Therefore, `interface_stats` includes only non-zero +> counters containing `err` or `drop`, aggregated as `all_interfaces`. + ## Label Values for `tcp_connection_stats` Below is a running list of all statistics for the metric `tcp_connection_stats`, captured from the `netstats` utility: @@ -108,3 +112,8 @@ Below is a running list of all statistics for the metric `tcp_connection_stats`, - `TWRecycled` - `TcpDuplicateDataRehash` - `TcpTimeoutRehash` + +> **Note:** This is a source-level list, not the current emitted allowlist. +> Production Linux emits only non-zero names in `netstatCuratedKeys`; for +> example, `TCPTSReorder` is currently filtered out. `ResetCount` is a Windows +> `hnsstats` statistic. diff --git a/docs/03-Metrics/plugins/Linux/tcpretrans.md b/docs/03-Metrics/plugins/Linux/tcpretrans.md index 81270750f3..fa924746c6 100644 --- a/docs/03-Metrics/plugins/Linux/tcpretrans.md +++ b/docs/03-Metrics/plugins/Linux/tcpretrans.md @@ -13,6 +13,10 @@ The plugin uses a native eBPF tracepoint (`tracepoint/tcp/tcp_retransmit_skb`) t The plugin does not generate Basic metrics. In Advanced mode (see [Metric Modes](../../modes/modes.md)), the plugin turns an eBPF result into an enriched `Flow` (adding Pod information based on IP), then sends the `Flow` to an external channel so that a tcpretrans module can create Pod-Level metrics. +> **Note:** This plugin must be present in `enabledPlugin` and Pod-Level metrics +> must be enabled. It emits `networkobservability_adv_tcpretrans_count` and is +> separate from node-wide retransmission-related statistics from `linuxutil`. + ### Code locations - Plugin and eBPF code: *pkg/plugin/tcpretrans/* diff --git a/docs/03-Metrics/plugins/readme.md b/docs/03-Metrics/plugins/readme.md index 6a8144a476..e6ee3f30fb 100644 --- a/docs/03-Metrics/plugins/readme.md +++ b/docs/03-Metrics/plugins/readme.md @@ -4,6 +4,10 @@ Each metric is associated with a Plugin. Associated metrics are linked below. See [Metrics Configuration](../configuration.md) for info on configuration. +The names in the table are the exact values accepted in the agent's +`enabledPlugin` configuration. Availability depends on the agent operating +system. + To run Retina without any plugins, the `CAP_BPF` capability (since Linux 5.8) is required for memory locking and for loading/using BPF programs. This capability is mandatory. If you're using any plugins, ensure that the necessary capabilities for those plugins are also added. If a plugin requires `CAP_SYS_ADMIN`, you can substitute it for `CAP_BPF`. | Name | Description | Metrics in Basic Mode | Metrics in Advanced Mode | Development Guide | @@ -12,6 +16,8 @@ To run Retina without any plugins, the `CAP_BPF` capability (since Linux 5.8) is | `dropreason` (Linux) | Counts number of packets/bytes dropped on a Node, along with the direction and reason for drop. | [Basic Mode](../modes/basic.md#plugin-dropreason-linux) | [Advanced Mode](../modes/advanced.md#plugin-dropreason-linux) | [Dev Guide](./Linux/dropreason.md) | | `linuxutil` (Linux) | Gathers TCP/UDP statistics and network interface statistics from the `netstats` and `ethtool` Node utilities (respectively). | [Basic Mode](../modes/basic.md#plugin-linuxutil-linux) | Same metrics as Basic mode | [Dev Guide](./Linux/linuxutil.md) | | `dns` (Linux) | Counts DNS requests/responses by query, including error codes, response IPs, and other metadata. | [Basic Mode](../modes/basic.md#plugin-dns-linux) | [Advanced Mode](../modes/advanced.md#plugin-dns-linux) | [Dev Guide](./Linux/dns.md) | -| `hnstats` (Windows) | Gathers TCP statistics and counts number of packets/bytes forwarded or dropped in HNS and VFP. | [Basic Mode](../modes/basic.md#plugin-hnsstats-windows) | Same metrics as Basic mode | [Dev Guide](./Windows/hnsstats.md) | +| `hnsstats` (Windows) | Gathers TCP statistics and counts number of packets/bytes forwarded or dropped in HNS and VFP. | [Basic Mode](../modes/basic.md#plugin-hnsstats-windows) | Same metrics as Basic mode | [Dev Guide](./Windows/hnsstats.md) | | `packetparser` (Linux) | Captures TCP and UDP packets traveling to and from pods and nodes. | No basic metrics | [Advanced Mode](../modes/advanced.md#plugin-packetparser-linux) | [Dev Guide](./Linux/packetparser.md) | -| `cilium` (Linux) | Collect agent and perf events from cilium via monitor1_2 socket and process flows in our hubble observer | [Metrics](./Linux/ciliumeventobserver.md#metrics) | Same metrics as Basic mode | [Dev Guide](./Linux/ciliumeventobserver.md) | +| `ciliumeventobserver` (Linux) | Collects agent and perf events from Cilium via the `monitor1_2` socket and processes flows in the Hubble observer. | [Metrics](./Linux/ciliumeventobserver.md#metrics) | Same metrics as Basic mode | [Dev Guide](./Linux/ciliumeventobserver.md) | +| `infiniband` (Linux) | Gathers NVIDIA InfiniBand port counters and interface status parameters. | InfiniBand node metrics | Same metrics as Basic mode | [Dev Guide](./Linux/infiniband.md) | +| `tcpretrans` (Linux) | Captures TCP retransmissions from the kernel tracepoint for Pod-Level metrics. | No basic metrics | [Advanced Mode](../modes/advanced.md#plugin-tcpretrans-linux) | [Dev Guide](./Linux/tcpretrans.md) |