From 5c26be4bac4153ab9fc678d90e034a9ca10587a2 Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Tue, 7 Jan 2025 17:50:00 +0000 Subject: [PATCH 1/7] chore(docs): Add doc for Hubble control plane and metrics --- docs/03-ControlPlane/cotrol_plane_intro.md | 4 ++ docs/03-Metrics/01-metrics-intro.md | 6 +++ docs/03-Metrics/hubble_metrics.md | 55 ++++++++++++++++++++++ docs/03-Metrics/modes/modes.md | 4 +- 4 files changed, 67 insertions(+), 2 deletions(-) create mode 100644 docs/03-ControlPlane/cotrol_plane_intro.md create mode 100644 docs/03-Metrics/01-metrics-intro.md create mode 100644 docs/03-Metrics/hubble_metrics.md diff --git a/docs/03-ControlPlane/cotrol_plane_intro.md b/docs/03-ControlPlane/cotrol_plane_intro.md new file mode 100644 index 0000000000..d391e4425a --- /dev/null +++ b/docs/03-ControlPlane/cotrol_plane_intro.md @@ -0,0 +1,4 @@ +# Control Planes +There are two control planes used in the Retina project: Hubble and the legacy control plane. Both control planes creates metrics and traces which are generated by the eBPF data plane, which has a single implementation. Only one control plane should be deployed at a given time. Helm charts for the deployment are found under `deploy/hubble/manifests/controller/helm/retina` and `deploy/legacy/manifests/controller/helm/retina`. + +> Note: Hubble offers additional features and metrics that the legacy control plane does not support. The plan is to deprecate the legacy control plane in favor of Hubble. For further documentation on Hubble, check [Cilium/Hubble repository](https://github.com/cilium/hubble/?tab=readme-ov-file#features) and official [Hubble metrics documentation](https://docs.cilium.io/en/stable/observability/metrics/#hubble-metrics) \ No newline at end of file diff --git a/docs/03-Metrics/01-metrics-intro.md b/docs/03-Metrics/01-metrics-intro.md new file mode 100644 index 0000000000..64d8704f2b --- /dev/null +++ b/docs/03-Metrics/01-metrics-intro.md @@ -0,0 +1,6 @@ +# Metrics + +Prometheus metrics available depend on the Retina control plane deployed: + +1. [Hubble metrics](./hubble_metrics.md) +2. [Legacy metrics](./modes/modes.md) \ No newline at end of file diff --git a/docs/03-Metrics/hubble_metrics.md b/docs/03-Metrics/hubble_metrics.md new file mode 100644 index 0000000000..fb308c4811 --- /dev/null +++ b/docs/03-Metrics/hubble_metrics.md @@ -0,0 +1,55 @@ +--- +sidebar_position: 1 +--- + +# Hubble Metrics +When Retina is deployed with Hubble control plane, the metrics include Node-level and Pod-level. Metrics are stored in Prometheus format, and can be viewed in Grafana. + +## Metrics + +* Node-Level Metrics: These metrics provide insights into traffic volume, dropped packets, number of connections, etc. by node. +* Hubble Metrics (DNS and Pod-Level Metrics): These metrics include source and destination pod information allowing to pinpoint network-related issues at a granular level. Metrics cover traffic volume, dropped packets, TCP resets, L4/L7 packet flows, etc. DNS metrics include DNS errors and DNS requests missing responses. + +### Node-Level Metrics + +The following metrics are aggregated per node. All metrics include labels: + +* `cluster` +* `instance` (Node name) + +Retina provides metrics for both Linux and Windows operating systems. +The table below outlines the different metrics generated. + +| Metric Name | Description | Extra Labels | Linux | Windows | +|------------------------------------------------|-------------|--------------|-------|---------| +| **networkobservability_forward_count** | Total forwarded packet count | `direction` | ✅ | ✅ | +| **networkobservability_forward_bytes** | Total forwarded byte count | `direction` | ✅ | ✅ | +| **networkobservability_drop_count** | Total dropped packet count | `direction`, `reason` | ✅ | ✅ | +| **networkobservability_drop_bytes** | Total dropped byte count | `direction`, `reason` | ✅ | ✅ | +| **networkobservability_tcp_state** | TCP currently active socket count by TCP state. | `state` | ✅ | ✅ | +| **networkobservability_tcp_connection_remote** | TCP currently active socket count by remote IP/port. | `address` (IP), `port` | ✅ | ❌ | +| **networkobservability_tcp_connection_stats** | TCP connection statistics. (ex: Delayed ACKs, TCPKeepAlive, TCPSackFailures) | `statistic` | ✅ | ✅ | +| **networkobservability_tcp_flag_counters** | TCP packets count by flag. | `flag` | ❌ | ✅ | +| **networkobservability_ip_connection_stats** | IP connection statistics. | `statistic` | ✅ | ❌ | +| **networkobservability_udp_connection_stats** | UDP connection statistics. | `statistic` | ✅ | ❌ | +| **networkobservability_udp_active_sockets** | UDP currently active socket count | | ✅ | ❌ | +| **networkobservability_interface_stats** | Interface statistics. | InterfaceName, `statistic` | ✅ | ✅ | + +### Pod-Level Metrics (Hubble Metrics) + +The following metrics are aggregated per pod (node information is preserved). All metrics include labels: + +* `cluster` +* `instance` (Node name) +* `source` or `destination` + +For *outgoing traffic*, there will be a `source` label with source pod namespace/name. +For *incoming traffic*, there will be a `destination` label with destination pod namespace/name. + +| Metric Name | Description | Extra Labels | Linux | Windows | +|----------------------------------|------------------------------|-----------------------|-------|---------| +| **hubble_dns_queries_total** | Total DNS requests by query | `source` or `destination`, `query`, `qtypes` (query type) | ✅ | ❌ | +| **hubble_dns_responses_total** | Total DNS responses by query/response | `source` or `destination`, `query`, `qtypes` (query type), `rcode` (return code), `ips_returned` (number of IPs) | ✅ | ❌ | +| **hubble_drop_total** | Total dropped packet count | `source` or `destination`, `protocol`, `reason` | ✅ | ❌ | +| **hubble_tcp_flags_total** | Total TCP packets count by flag. | `source` or `destination`, `flag` | ✅ | ❌ | +| **hubble_flows_processed_total** | Total network flows processed (L4/L7 traffic) | `source` or `destination`, `protocol`, `verdict`, `type`, `subtype` | ✅ | ❌ | \ No newline at end of file diff --git a/docs/03-Metrics/modes/modes.md b/docs/03-Metrics/modes/modes.md index 11eb3ac720..a19dba64a8 100644 --- a/docs/03-Metrics/modes/modes.md +++ b/docs/03-Metrics/modes/modes.md @@ -1,7 +1,7 @@ --- -sidebar_position: 1 +sidebar_position: 2 --- -# Metric Modes +# Legacy Metric Modes Retina provides **three modes** with their own metrics and scale capabilities. Each mode is **fully customizable** (only create the metrics/labels you need). From c894fae813817be2a53fc7943a50aed96aced827 Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Tue, 7 Jan 2025 18:20:48 +0000 Subject: [PATCH 2/7] chore(docs): fix markdown linting --- docs/03-ControlPlane/cotrol_plane_intro.md | 3 ++- docs/03-Metrics/01-metrics-intro.md | 2 +- docs/03-Metrics/hubble_metrics.md | 3 ++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/03-ControlPlane/cotrol_plane_intro.md b/docs/03-ControlPlane/cotrol_plane_intro.md index d391e4425a..2e7e4716fb 100644 --- a/docs/03-ControlPlane/cotrol_plane_intro.md +++ b/docs/03-ControlPlane/cotrol_plane_intro.md @@ -1,4 +1,5 @@ # Control Planes + There are two control planes used in the Retina project: Hubble and the legacy control plane. Both control planes creates metrics and traces which are generated by the eBPF data plane, which has a single implementation. Only one control plane should be deployed at a given time. Helm charts for the deployment are found under `deploy/hubble/manifests/controller/helm/retina` and `deploy/legacy/manifests/controller/helm/retina`. -> Note: Hubble offers additional features and metrics that the legacy control plane does not support. The plan is to deprecate the legacy control plane in favor of Hubble. For further documentation on Hubble, check [Cilium/Hubble repository](https://github.com/cilium/hubble/?tab=readme-ov-file#features) and official [Hubble metrics documentation](https://docs.cilium.io/en/stable/observability/metrics/#hubble-metrics) \ No newline at end of file +> Note: Hubble offers additional features and metrics that the legacy control plane does not support. The plan is to deprecate the legacy control plane in favor of Hubble. For further documentation on Hubble, check [Cilium/Hubble repository](https://github.com/cilium/hubble/?tab=readme-ov-file#features) and official [Hubble metrics documentation](https://docs.cilium.io/en/stable/observability/metrics/#hubble-metrics) diff --git a/docs/03-Metrics/01-metrics-intro.md b/docs/03-Metrics/01-metrics-intro.md index 64d8704f2b..e9ca33bd91 100644 --- a/docs/03-Metrics/01-metrics-intro.md +++ b/docs/03-Metrics/01-metrics-intro.md @@ -3,4 +3,4 @@ Prometheus metrics available depend on the Retina control plane deployed: 1. [Hubble metrics](./hubble_metrics.md) -2. [Legacy metrics](./modes/modes.md) \ No newline at end of file +2. [Legacy metrics](./modes/modes.md) diff --git a/docs/03-Metrics/hubble_metrics.md b/docs/03-Metrics/hubble_metrics.md index fb308c4811..beafac47d0 100644 --- a/docs/03-Metrics/hubble_metrics.md +++ b/docs/03-Metrics/hubble_metrics.md @@ -3,6 +3,7 @@ sidebar_position: 1 --- # Hubble Metrics + When Retina is deployed with Hubble control plane, the metrics include Node-level and Pod-level. Metrics are stored in Prometheus format, and can be viewed in Grafana. ## Metrics @@ -52,4 +53,4 @@ For *incoming traffic*, there will be a `destination` label with destination pod | **hubble_dns_responses_total** | Total DNS responses by query/response | `source` or `destination`, `query`, `qtypes` (query type), `rcode` (return code), `ips_returned` (number of IPs) | ✅ | ❌ | | **hubble_drop_total** | Total dropped packet count | `source` or `destination`, `protocol`, `reason` | ✅ | ❌ | | **hubble_tcp_flags_total** | Total TCP packets count by flag. | `source` or `destination`, `flag` | ✅ | ❌ | -| **hubble_flows_processed_total** | Total network flows processed (L4/L7 traffic) | `source` or `destination`, `protocol`, `verdict`, `type`, `subtype` | ✅ | ❌ | \ No newline at end of file +| **hubble_flows_processed_total** | Total network flows processed (L4/L7 traffic) | `source` or `destination`, `protocol`, `verdict`, `type`, `subtype` | ✅ | ❌ | From a8c0cf7c5a975f26d2a4c64bc62fe0a4a3bf4d18 Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Wed, 8 Jan 2025 09:48:07 +0000 Subject: [PATCH 3/7] chore(docs): both source and dest labels can be present --- docs/03-Metrics/hubble_metrics.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/03-Metrics/hubble_metrics.md b/docs/03-Metrics/hubble_metrics.md index beafac47d0..b7dda64c22 100644 --- a/docs/03-Metrics/hubble_metrics.md +++ b/docs/03-Metrics/hubble_metrics.md @@ -42,7 +42,8 @@ The following metrics are aggregated per pod (node information is preserved). Al * `cluster` * `instance` (Node name) -* `source` or `destination` +* `source` +* `destination` For *outgoing traffic*, there will be a `source` label with source pod namespace/name. For *incoming traffic*, there will be a `destination` label with destination pod namespace/name. From 3270677621a01fe2b6045c83c1cf5db7e372eda8 Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Wed, 8 Jan 2025 15:24:37 +0000 Subject: [PATCH 4/7] chore(docs): grammar fix --- docs/03-ControlPlane/cotrol_plane_intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/03-ControlPlane/cotrol_plane_intro.md b/docs/03-ControlPlane/cotrol_plane_intro.md index 2e7e4716fb..2d24cfd4e4 100644 --- a/docs/03-ControlPlane/cotrol_plane_intro.md +++ b/docs/03-ControlPlane/cotrol_plane_intro.md @@ -1,5 +1,5 @@ # Control Planes -There are two control planes used in the Retina project: Hubble and the legacy control plane. Both control planes creates metrics and traces which are generated by the eBPF data plane, which has a single implementation. Only one control plane should be deployed at a given time. Helm charts for the deployment are found under `deploy/hubble/manifests/controller/helm/retina` and `deploy/legacy/manifests/controller/helm/retina`. +There are two control planes used in the Retina project: Hubble and the legacy control plane. Both control planes create metrics and traces which are generated by the eBPF data plane, which has a single implementation. Only one control plane should be deployed at a given time. Helm charts for the deployment are found under `deploy/hubble/manifests/controller/helm/retina` and `deploy/legacy/manifests/controller/helm/retina`. > Note: Hubble offers additional features and metrics that the legacy control plane does not support. The plan is to deprecate the legacy control plane in favor of Hubble. For further documentation on Hubble, check [Cilium/Hubble repository](https://github.com/cilium/hubble/?tab=readme-ov-file#features) and official [Hubble metrics documentation](https://docs.cilium.io/en/stable/observability/metrics/#hubble-metrics) From 55cbbea37da54e56fdb452123c18de207305795d Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Fri, 10 Jan 2025 15:16:51 +0000 Subject: [PATCH 5/7] chore(docs): add control plane intro to metrics page --- docs/03-ControlPlane/cotrol_plane_intro.md | 5 ----- docs/03-Metrics/01-metrics-intro.md | 9 ++++++++- 2 files changed, 8 insertions(+), 6 deletions(-) delete mode 100644 docs/03-ControlPlane/cotrol_plane_intro.md diff --git a/docs/03-ControlPlane/cotrol_plane_intro.md b/docs/03-ControlPlane/cotrol_plane_intro.md deleted file mode 100644 index 2d24cfd4e4..0000000000 --- a/docs/03-ControlPlane/cotrol_plane_intro.md +++ /dev/null @@ -1,5 +0,0 @@ -# Control Planes - -There are two control planes used in the Retina project: Hubble and the legacy control plane. Both control planes create metrics and traces which are generated by the eBPF data plane, which has a single implementation. Only one control plane should be deployed at a given time. Helm charts for the deployment are found under `deploy/hubble/manifests/controller/helm/retina` and `deploy/legacy/manifests/controller/helm/retina`. - -> Note: Hubble offers additional features and metrics that the legacy control plane does not support. The plan is to deprecate the legacy control plane in favor of Hubble. For further documentation on Hubble, check [Cilium/Hubble repository](https://github.com/cilium/hubble/?tab=readme-ov-file#features) and official [Hubble metrics documentation](https://docs.cilium.io/en/stable/observability/metrics/#hubble-metrics) diff --git a/docs/03-Metrics/01-metrics-intro.md b/docs/03-Metrics/01-metrics-intro.md index e9ca33bd91..915b8841fd 100644 --- a/docs/03-Metrics/01-metrics-intro.md +++ b/docs/03-Metrics/01-metrics-intro.md @@ -1,6 +1,13 @@ # Metrics -Prometheus metrics available depend on the Retina control plane deployed: +Prometheus metrics available depend on the Retina control plane deployed. + +## Control Planes + +There are two control planes used in the Retina project: Hubble and the legacy control plane. Both control planes create metrics and traces which are generated by the eBPF data plane, which has a single implementation. Only one control plane should be deployed at a given time. Helm charts for the deployment are found under `deploy/hubble/manifests/controller/helm/retina` and `deploy/legacy/manifests/controller/helm/retina`. 1. [Hubble metrics](./hubble_metrics.md) 2. [Legacy metrics](./modes/modes.md) + + +> Note: Hubble offers additional features and metrics that the legacy control plane does not support. The plan is to deprecate the legacy control plane in favor of Hubble. For further documentation on Hubble, check [Cilium/Hubble repository](https://github.com/cilium/hubble/?tab=readme-ov-file#features) and official [Hubble metrics documentation](https://docs.cilium.io/en/stable/observability/metrics/#hubble-metrics) From 95f2c1cb8dcfaa32896e2cf1598fc9a72388fd6f Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Fri, 10 Jan 2025 15:18:50 +0000 Subject: [PATCH 6/7] chore(docs): fix linting --- docs/03-Metrics/01-metrics-intro.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/03-Metrics/01-metrics-intro.md b/docs/03-Metrics/01-metrics-intro.md index 915b8841fd..70075df8b2 100644 --- a/docs/03-Metrics/01-metrics-intro.md +++ b/docs/03-Metrics/01-metrics-intro.md @@ -9,5 +9,4 @@ There are two control planes used in the Retina project: Hubble and the legacy c 1. [Hubble metrics](./hubble_metrics.md) 2. [Legacy metrics](./modes/modes.md) - > Note: Hubble offers additional features and metrics that the legacy control plane does not support. The plan is to deprecate the legacy control plane in favor of Hubble. For further documentation on Hubble, check [Cilium/Hubble repository](https://github.com/cilium/hubble/?tab=readme-ov-file#features) and official [Hubble metrics documentation](https://docs.cilium.io/en/stable/observability/metrics/#hubble-metrics) From ed25302b08c6ab555785556aa1ce688692b6556b Mon Sep 17 00:00:00 2001 From: Simone Rodigari Date: Fri, 10 Jan 2025 15:22:14 +0000 Subject: [PATCH 7/7] chore(docs): address comment on sidebar ordering --- docs/03-Metrics/{hubble_metrics.md => 02-hubble_metrics.md} | 4 ---- 1 file changed, 4 deletions(-) rename docs/03-Metrics/{hubble_metrics.md => 02-hubble_metrics.md} (99%) diff --git a/docs/03-Metrics/hubble_metrics.md b/docs/03-Metrics/02-hubble_metrics.md similarity index 99% rename from docs/03-Metrics/hubble_metrics.md rename to docs/03-Metrics/02-hubble_metrics.md index b7dda64c22..502ab5ae90 100644 --- a/docs/03-Metrics/hubble_metrics.md +++ b/docs/03-Metrics/02-hubble_metrics.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 1 ---- - # Hubble Metrics When Retina is deployed with Hubble control plane, the metrics include Node-level and Pod-level. Metrics are stored in Prometheus format, and can be viewed in Grafana.