Docs: Create network metrics docs

docs/sources/network/_index.md

@@ -0,0 +1,74 @@
+---
+title: Network metrics
+menuTitle: Network
+description: Configuring Beyla to observe point-to-point network metrics.
+weight: 1
+keywords:
+  - Beyla
+  - eBPF
+  - Network
+---
+
+{{% admonition type="warning" %}}
+Network metrics is an [experimental](/docs/release-life-cycle/) under development feature, expect breaking changes.
+{{% /admonition %}}
+
+# Network metrics
+
+Grafana Beyla can be configured to provide network metrics between different endpoints. For example, between physical nodes, containers, Kubernetes pods, services, etc.
+
+{{% admonition type="note" %}}
+Prometheus exporting for network metrics is not currently supported.
+{{% /admonition %}}
+
+## Get started
+
+To get started using Beyla networking metrics, consult the [quickstart setup documentation]({{< relref "./quickstart" >}}), and for advanced configuration, consult the [configuration documentation]({{< relref "./config" >}}).
+
+## Metric attributes
+
+Network metrics provides a single **OpenTelemetry** metric `beyla.network.flow.bytes`, a counter of Number of bytes observed between two network endpoints, with the following attributes:
+
+| Attribute name       | Description                                                                                                                                                                         |
+|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `beyla.ip`           | Local IP address of the Beyla instance that emitted the metric                                                                                                                      |
+| `src.address`        | Source IP address of Network flow                                                                                                                                                   |
+| `dst.address`        | Destination IP address of Network flow                                                                                                                                              |
+| `src.name`           | Name of Network flow source: Kubernetes name, host name, or IP address                                                                                                              |
+| `dst.name`           | Name of Network flow destination: Kubernetes name, host name, or IP address                                                                                                         |
+| `src.namespace`      | Namespace of Network flow source. Could be empty in non-Kubernetes flows                                                                                                            |
+| `dst.namespace`      | Namespace of Network flow destination. Could be empty in non-Kubernetes flows                                                                                                       |
+| `src.cidr`           | If the [`cidrs` configuration section]({{< relref "./config" >}}) is set, the CIDR that matches the source IP address                                                               |
+| `dst.cidr`           | If the [`cidrs` configuration section]({{< relref "./config" >}}) is set, the CIDR that matches the destination IP address                                                          |
+| `k8s.src.namespace`  | Kubernetes namespace of the source of the flow                                                                                                                                      |
+| `k8s.dst.namespace`  | Kubernetes namespace of the destination of the flow                                                                                                                                 |
+| `k8s.src.name`       | Name of the source Pod, Service, or Node                                                                                                                                            |
+| `k8s.dst.name`       | Name of the destination Pod, Service, or Node                                                                                                                                       |
+| `k8s.src.owner.name` | Name of the owner of the source Pod. If there is no owner, the Pod name is used                                                                                                     |
+| `k8s.dst.owner.name` | Name of the owner of the destination Pod. If there is no owner, the Pod name is used                                                                                                |
+| `k8s.src.owner.type` | Type of the owner of the source Pod: `Deployment`, `DaemonSet`, `ReplicaSet`, `StatefulSet`, or `Pod` if there is no owner                                                          |
+| `k8s.dst.owner.type` | Type of the owner of the destination Pod: `Deployment`, `DaemonSet`, `ReplicaSet`, `StatefulSet`, or `Pod` if there is no owner                                                     |
+| `k8s.src.node.ip`    | IP address of the source Node                                                                                                                                                       |
+| `k8s.dst.node.ip`    | IP address of the destination Node                                                                                                                                                  |
+| `k8s.src.node.name`  | Name of the source Node                                                                                                                                                             |
+| `k8s.dst.node.name`  | Name of the destination Node                                                                                                                                                        |
+| `k8s.cluster.name`   | Name of the Kubernetes cluster. Beyla can auto-detect it on Google Cloud, Microsoft Azure, and Amazon Web Services. For other providers, set the `BEYLA_KUBE_CLUSTER_NAME` property |
+
+### Allowed attributes
+
+If the metric with all the attributes is reported it might lead to a cardinality explosion, especially when including external traffic in the `src.address`/`dst.address` attributes.
+
+You can specify which attributes are allowed in the Beyla configuration. Allowed attributes and aggregates the metrics by them. For example:
+
+```yaml
+network:
+  enable: true
+  allowed_attributes:
+    - k8s.src.owner.name
+    - k8s.src.namespace
+    - k8s.dst.owner.name
+    - k8s.dst.namespace
+```
+
+In this example, the bytes metric is the aggregated by the source and destination owners. This is, all the
+pods from a given Deployment/StatefulSet/ReplicaSet/DaemonSet.

docs/sources/network/config.md

@@ -0,0 +1,177 @@
+---
+title: Beyla Network Metrics configuration options
+menuTitle: Configuration
+description: Learn about the configuration options available for Beyla network metrics
+weight: 2
+keywords:
+  - Beyla
+  - eBPF
+  - Network
+---
+
+{{% admonition type="warning" %}}
+Network metrics is an [experimental](/docs/release-life-cycle/) under development feature, expect breaking changes.
+{{% /admonition %}}
+
+# Beyla Network Metrics configuration options
+
+Network metrics are configured under the `network` property of the [Beyla Configuration YAML file]({{< relref "../configure/options" >}}) or with a set of environment variables prefixed as `BEYLA_NETWORK_`.
+
+Example YAML:
+
+```yaml
+network:
+  enable: true
+  allowed_attributes:
+    - k8s.src.owner.name
+    - k8s.src.namespace
+    - k8s.dst.owner.name
+    - k8s.dst.namespace
+    - src.cidr
+    - dst.cidr
+  cidrs:
+    - 10.10.0.0/24
+    - 10.0.0.0/8
+    - 10.30.0.0/16
+```
+
+## Network metrics configuration properties
+
+| YAML     | Environment variable    | Type    | Default |
+| -------- | ----------------------- | ------- | ------- |
+| `enable` | `BEYLA_NETWORK_METRICS` | boolean | `false` |
+
+Enables network metrics reporting in Beyla.
+
+| YAML                 | Environment variable               | Type     | Default |
+| -------------------- | ---------------------------------- | -------- | ------- |
+| `allowed_attributes` | `BEYLA_NETWORK_ALLOWED_ATTRIBUTES` | []string | (empty) |
+
+Specifies which attributes are visible in the metrics.
+Beyla aggregates the metrics by their common visible attributes.
+For example, hiding the `k8s.src.name` and allowing `k8s.src.owner.name` would aggregate the metrics of all the pods under a same owner.
+
+This property won't filter some meta-attributes such as `instance`, `job`, `service.instance.id`, `service_name`, `telemetry.sdk.*`, etc.
+
+{{% admonition type="note" %}}
+If left empty, Beyla reports all attributes; which might greatly increase the cardinality of your metrics.
+Setting this value to list only the attributes you really need is highly recommended.
+{{% /admonition %}}
+
+See the [network metrics documentation]({{< relref "./_index.md" >}}) for a detailed list of all the available attributes.
+
+If you set this property via environment variable each entry must be separated by a comma, for example:
+
+```sh
+BEYLA_NETWORK_ALLOWED_ATTRIBUTES=src.name,dst.name
+```
+
+| YAML    | Environment variable  | Type     | Default |
+| ------- | --------------------- | -------- | ------- |
+| `cidrs` | `BEYLA_NETWORK_CIDRS` | []string | (empty) |
+
+CIDRs list, to be set as the `src.cidr` and `dst.cidr` attribute with the entry that matches the `src.address` and `dst.address` respectively.
+
+Attribute as a function of the source and destination IP addresses.
+If an IP does not match any address here, the attributes won't be set.
+If an IP matches multiple CIDR definitions, the flow is decorated with the narrowest CIDR.
+As a result, you can safely add a 0.0.0.0/0 entry to group there all the traffic that does not match any of the other CIDRs.
+
+If you set this property via environment variable each entry must be separated by a comma, for example:
+
+```sh
+BEYLA_NETWORK_CIDRS=10.0.0.0/8,192.168.0.0/16
+```
+
+| YAML       | Environment variable     | Type   | Default   |
+| ---------- | ------------------------ | ------ | --------- |
+| `agent_ip` | `BEYLA_NETWORK_AGENT_IP` | string | (not set) |
+
+Allows overriding the reported `beyla.ip` attribute on each metric.
+If not set, Beyla automatically detects its own IP from the specified network interface (see next property).
+
+| YAML             | Environment variable           | Type   | Default    |
+| ---------------- | ------------------------------ | ------ | ---------- |
+| `agent_ip_iface` | `BEYLA_NETWORK_AGENT_IP_IFACE` | string | `external` |
+
+Specifies which interface should Beyla use to pick its own IP address to set the value of the `beyla.ip` attribute.
+Accepted values are: `external` (default), `local`, or `name:<interface name>` (e.g. `name:eth0`).
+
+If the `agent_ip` configuration property is set, this property has no effect.
+
+| YAML            | Environment variable          | Type   | Default |
+| --------------- | ----------------------------- | ------ | ------- |
+| `agent_ip_type` | `BEYLA_NETWORK_AGENT_IP_TYPE` | string | `any`   |
+
+Specifies which type of IP address (IPv4 or IPv6 or both) should the Beyla report in the `beyla.ip` field of each flow.
+Accepted values are: `any` (default), `ipv4`, `ipv6`.
+If the `agent_ip` configuration property is set, this property has no effect.
+
+| YAML         | Environment variable       | Type     | Default |
+| ------------ | -------------------------- | -------- | ------- |
+| `interfaces` | `BEYLA_NETWORK_INTERFACES` | []string | (empty) |
+
+Contains the interface names from where flows are collected from.
+If empty, Beyla fetches all the interfaces in the system, excepting the ones listed in `excluded_interfaces`
+(see below).
+If an entry is enclosed by slashes (e.g. `/br-/`), it is matched as regular expression, otherwise it is matched as a case-sensitive string.
+
+If you set this property via environment variable each entry must be separated by a comma, for example:
+
+```
+BEYLA_NETWORK_INTERFACES=eth0,eth1,/^veth/
+```
+
+| YAML                 | Environment variable               | Type     | Default |
+| -------------------- | ---------------------------------- | -------- | ------- |
+| `exclude_interfaces` | `BEYLA_NETWORK_EXCLUDE_INTERFACES` | []string | `lo`    |
+
+Contains the interface names to be excluded from network flow tracing.
+Default: `lo` (loop-back).
+If an entry is enclosed by slashes (e.g. `/br-/`), it is matched as a regular expression, otherwise it is matched as a case-sensitive string.
+
+If you set this property via environment variable each entry must be separated by a comma, for example:
+
+```
+BEYLA_NETWORK_EXCLUDE_INTERFACES=lo,/^veth/
+```
+
+| YAML              | Environment variable            | Type    | Default |
+| ----------------- | ------------------------------- | ------- | ------- |
+| `cache_max_flows` | `BEYLA_NETWORK_CACHE_MAX_FLOWS` | integer | `5000`  |
+
+Specifies how many flows can be accumulated in the accounting cache before being flushed for its later export.
+Default value is 5000.
+Decrease it if you see the "received message larger than max" error in Beyla logs.
+
+| YAML                   | Environment variable                 | Type     | Default |
+| ---------------------- | ------------------------------------ | -------- | ------- |
+| `cache_active_timeout` | `BEYLA_NETWORK_CACHE_ACTIVE_TIMEOUT` | duration | `5s`    |
+
+Specifies the maximum duration that flows are kept in the accounting cache before being flushed for its later export.
+
+| YAML        | Environment variable      | Type   | Default |
+| ----------- | ------------------------- | ------ | ------- |
+| `direction` | `BEYLA_NETWORK_DIRECTION` | string | `both`  |
+
+Allows selecting which flows to trace according to its direction in the interface where they are captured from.
+Accepted values are `ingress`, `egress`, or `both` (default).
+
+It's important to emphasize that, in this context, _ingress_ or _egress_ are not related to incoming/outgoing
+traffic from outside the node or the cluster, but the network interface.
+This means that the same network packet could be seen as "ingress" in a virtual network device and as "egress" in the backing physical network interface.
+
+| YAML       | Environment variable     | Type    | Default        |
+| ---------- | ------------------------ | ------- | -------------- |
+| `sampling` | `BEYLA_NETWORK_SAMPLING` | integer | `0` (disabled) |
+
+Sampling holds the rate at which packets should be sampled and sent to the target collector.
+E.g. if set to 100, one out of 100 packets, on average, are sent to the target collector.
+
+
+| YAML          | Environment variable        | Type    | Default |
+| ------------- | --------------------------- | ------- | ------- |
+| `print_flows` | `BEYLA_NETWORK_PRINT_FLOWS` | boolean | `false` |
+
+If set to `true`, Beyla prints each Network flow in the standard output.
+It might generate a lot of output.