Network metrics on Grafana Labs

Beyla network metrics quickstart

Wed, 15 Apr 2026 16:46:57 +0000

Beyla network metrics quickstart

Beyla can generate network metrics in any environment (physical host, virtual host, or container). It’s recommended to use a Kubernetes environment, as Beyla is able to decorate each metric with the metadata of the source and destination Kubernetes entities.

Note
This tutorial describes how to deploy Beyla in Kubernetes from scratch. To use Helm, consult the Deploy Beyla in Kubernetes with Helm documentation.

Deploy Beyla with network metrics

To enable network metrics, set the following option in your Beyla configuration:

network:
  enable: true

Or export the following environment variable

export BEYLA_NETWORK_METRICS=true

Network metrics requires metrics to be decorated with Kubernetes metadata. To enable this feature, set the following option in your Beyla configuration:

attributes:
  kubernetes:
    enable : true

Or export the following environment variable

export BEYLA_KUBE_METADATA_ENABLE=true

Finally, network metrics requires elevated privileges. Running with sudo or privileged: true for Kubernetes is the simplest approach. For more restrictive environments, Beyla can run with specific Linux capabilities. Refer to Security, permissions and capabilities for details on the required capabilities for your use case.

To learn more about Beyla configuration, consult the Beyla configuration documentation.

Example configuration

The following YAML configuration provides a simple Beyla deployment for network metrics:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: beyla
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: beyla
rules:
  - apiGroups: [ "apps" ]
    resources: [ "replicasets" ]
    verbs: [ "list", "watch" ]
  - apiGroups: [ "" ]
    resources: [ "pods", "services", "nodes" ]
    verbs: [ "list", "watch" ]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: beyla
subjects:
  - kind: ServiceAccount
    name: beyla
    namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: beyla
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: beyla-config
data:
  beyla-config.yml: |
    attributes:
      kubernetes:
        enable: true
    network:
      enable: true
      print_flows: true
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: beyla
spec:
  selector:
    matchLabels:
      instrumentation: beyla
  template:
    metadata:
      labels:
        instrumentation: beyla
    spec:
      serviceAccountName: beyla
      hostNetwork: true
      volumes:
        - name: beyla-config
          configMap:
            name: beyla-config
      containers:
        - name: beyla
          image: grafana/beyla:main
          securityContext:
            privileged: true
          volumeMounts:
            - mountPath: /config
              name: beyla-config
          env:
            - name: BEYLA_CONFIG_PATH
              value: "/config/beyla-config.yml"

Note the following requirements for this deployment configuration:

The container image uses the latest under-development grafana/beyla:main image.
Beyla needs to run as a DaemonSet, as it is requires only one Beyla instance per node
To listen to network packets on the host, Beyla requires the hostNetwork: true permission
To decorate the network metrics with Kubernetes metadata, create a ClusterRole and ClusterRoleBinding with list and watch permissions for ReplicaSets, Pods, Services and Nodes

The configuration does not set an endpoint to export metrics. Instead, the trace_printer: text option outputs the captured network flows to standard output.

Use kubectl logs to see network flow entries, for example:

network_flow: beyla.ip=172.18.0.2 iface= direction=255 src.address=10.244.0.4 dst.address=10.96.0.1
src.name=local-path-provisioner-7577fdbbfb-g6b7d dst.name=kubernetes
k8s.src.node.name=kind-control-plane k8s.dst.namespace=default k8s.dst.name=kubernetes
k8s.dst.owner.type=Service k8s.src.namespace=local-path-storage
k8s.src.name=local-path-provisioner-7577fdbbfb-g6b7d k8s.src.type=Pod
k8s.src.owner.name=local-path-provisioner k8s.src.owner.type=Deployment
k8s.dst.type=Service k8s.dst.owner.name=kubernetes

For further information on the attributes used, consult the network metrics documentation.

Export OpenTelemetry metrics

After you have confirmed that network metrics are being collected, configure Beyla to export the metrics in OpenTelemetry format to an OpenTelemetry endpoint.

Note
Prometheus exporting for network metrics is not currently supported.

Beyla works with any OpenTelemetry endpoint. This quickstart uses the OpenTelemetry endpoint in Grafana Cloud. You can get a Free Grafana Cloud Account at Grafana’s website.

To get your stack’s OpenTelemetry endpoint, login to the Grafana Cloud Portal, and click Configure under the OpenTelemetry section.

Under Password / API token, click Generate now and follow the instructions to create an API token.

The Environment Variables section is populated with a set of standard OpenTelemetry environment variables which provide the connection endpoint and credentials information for Beyla.

Copy the value of OTEL_EXPORTER_OTLP_HEADERS environment variable and paste it as a Kubernetes secret (and deploy it):

apiVersion: v1
kind: Secret
metadata:
  name: grafana-secret
type: Opaque
stringData:
  otlp-headers: "Authorization=Basic MzQ3NTp....."

Now add the OTEL_EXPORTER_OTLP_HEADERS and reference this secret as the variable value.

Also Add OTEL_EXPORTER_OTLP_ENDPOINT and its value as an environment variable to the Beyla container in the Kubernetes manifest. The env section of the beyla container in the manifest from the start of this document should look like:

          env:
            - name: BEYLA_CONFIG_PATH
              value: "/config/beyla-config.yml"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
            - name: OTEL_EXPORTER_OTLP_HEADERS
              valueFrom:
                secretKeyRef:
                  key: otlp-headers
                  name: grafana-secret

Select metrics attributes to reduce cardinality

Be default, Beyla includes the following attributes in the beyla.network.flow.bytes metric:

k8s.src.owner.name
k8s.src.namespace
k8s.dst.owner.name
k8s.dst.namespace
k8s.cluster.name

Beyla only includes a subset of the available attributes to avoid leading to a cardinality explosion in the metrics storage, especially if some attributes like src.address or dst.address capture the IP addresses of the external traffic.

The attributes.select.<metric-name>.include YAML subsection makes it possible to select the attributes to report:

network:
  enable: true
attributes:
  kubernetes:
    enable: true
  select:
    beyla.network.flow.bytes:
      include:
      - k8s.src.owner.name
      - k8s.src.namespace
      - k8s.dst.owner.name
      - k8s.dst.namespace

The previous example would aggregate the beyla.network.flow.bytes value by source and destination Kubernetes owner (Deployment, DaemonSet, StatefulSet, ReplicaSet), avoiding finer-grained attributes such as Pod name or IP addresses.

Group IP addresses by CIDR

Reporting metric attributes containing IP addresses (src.address and dst.address) might lead to cardinality explosion, however it might be a useful network-level information to get a better view about how networks and sub-networks communicate.

The cidrs YAML subsection in network (or the BEYLA_NETWORK_CIDRS environment variable) accepts a list of subnets in CIDR notation, in both IPv4 and IPv6 format.

The existence of the cidrs section leaves the src.address and dst.address fields untouched, and adds the src.cidr and dst.cidr attributes. Don’t forget to add them to the attributes.select section:

network:
  enable: true
  cidrs:
    - 10.10.0.0/24
    - 10.0.0.0/8
    - 10.30.0.0/16
attributes:
  kubernetes:
    enable: true
  select:
    beyla_network_flow_bytes:
      include:
          - k8s.src.owner.name
          - k8s.src.namespace
          - k8s.dst.owner.name
          - k8s.dst.namespace
          - src.cidr
          - dst.cidr

Measure traffic between Cloud availability zones

Wed, 15 Apr 2026 16:46:57 +0000

Measure traffic between Cloud availability zones

Note
This feature is currently only available in Kubernetes clusters.

Traffic between Cloud Availability Zones might incur additional costs. Beyla is able to measure it either by adding src.zone and dst.zone attributes to regular network metrics, or by providing a separate beyla.network.inter.zone.bytes (OTEL) / beyla_network_inter_zone_bytes_total (Prometheus) metric.

Add `src.zone` and `dst.zone` attributes to regular network metrics

Source and destination availability zone attributes are disabled by default in Beyla. To enable it, explicitly add them to the list of included network attributes in the Beyla YAML configuration:

attributes:
  select:
    beyla_network_flow_bytes:
      include:
        - k8s.src.owner.name
        - k8s.src.namespace
        - k8s.dst.owner.name
        - k8s.dst.namespace
        - k8s.cluster.name
        - src.zone
        - dst.zone

This configuration makes inter-zone traffic visible for each beyla_network_flow_bytes_total metric with different src_zone and dst_zone attributes.

If you require higher granularity in your inter-zone traffic measurement (for example, source/destination pods or nodes), adding zone attributes would impact the cardinality of the metric, even for traffic within the same availability zone.

Use the `beyla.network.inter.zone` metric

Using a separate metric for inter-zone traffic reduces the metric cardinality impact of collecting this data, because the src.zone and dst.zone attributes are not added to the regular network metrics.

To enable the beyla.network.inter.zone metric, add the network_inter_zone option to the BEYLA_OTEL_METRICS_FEATURES or BEYLA_PROMETHEUS_FEATURES configuration option, or its equivalent YAML options. For example, if Beyla is configured to export metrics via OpenTelemetry:

otel_metrics_export:
  features:
    - network
    - network_inter_zone

By default, the beyla.network.inter.zone metric includes only high-level attributes such as zone information and source/destination owner names to keep metric cardinality low. However, you might want to analyze inter-zone traffic at a more granular level, such as by individual pods or nodes, to identify specific sources of cross-zone communication.

To include additional attributes for detailed analysis, configure attribute selection specifically for the inter-zone metric:

attributes:
  select:
    beyla_network_inter_zone_bytes:
      include:
        - k8s.src.namespace
        - k8s.src.pod.name
        - k8s.src.node.name
        - k8s.dst.namespace
        - k8s.dst.pod.name
        - k8s.dst.node.name
        - k8s.cluster.name
        - src.zone
        - dst.zone

This configuration provides detailed visibility into which specific pods and nodes generate inter-zone traffic, helping you optimize your application topology and reduce cross-zone costs.

Note
Adding more attributes increases the metric cardinality.

PromQL queries to measure inter-zone traffic

Assuming that both network and network_inter_zone metric families are enabled, you can use the following PromQL queries to measure inter-zone traffic:

Overall inter-zone traffic throughput:

sum(rate(beyla_network_inter_zone_bytes_total[$__rate_interval]))

Inter-zone traffic throughput, summarized by source and destination zones:

sum(rate(beyla_network_inter_zone_bytes_total[$__rate_interval])) by(src_zone,dst_zone)

Overall same-zone traffic throughput:

sum(rate(beyla_network_flow_bytes_total[$__rate_interval]))
  - sum(rate(beyla_network_inter_zone_bytes_total[$__rate_interval]))

Percentage of inter-zone traffic from the total:

100 * sum(rate(beyla_network_inter_zone_bytes_total[$__rate_interval]))
  / sum(rate(beyla_network_flow_bytes_total[$__rate_interval]))

Set up Beyla network metrics in Kubernetes with Helm for Asserts

Wed, 15 Apr 2026 16:46:57 +0000

Set up Beyla network metrics in Kubernetes with Helm for Asserts

Asserts works with Beyla and requires Beyla network metrics. Learn how to set up Beyla network metrics in Kubernetes with Helm to export telemetry data to Asserts.

To learn more about Beyla network metrics, consult the Network documentation.

Prerequisites

Before you install Beyla network metrics and export telemetry data to Asserts you need:

A free Grafana Cloud account.
Access rights to a Kubernetes cluster, enough to create components with privileges.

You can register for a free forever Grafana Cloud account in minutes and start sending telemetry data and monitoring your infrastructure and applications.

There are two configuration options to collect metrics to send to Grafana Cloud for Asserts. First, through Kubernetes monitoring or alternatively with an OpenTelemetry Collector.

Configuration for Kubernetes monitoring

If you use Kubernetes monitoring and a Helm chart for scraping metrics, create a values.yml with the following configuration:

preset: network

podAnnotations:
  k8s.grafana.com/scrape: true
  k8s.grafana.com/job: beyla-network
  k8s.grafana.com/metrics.portName: metrics

Configure for OpenTelemetry Collector

If you use an OpenTelemetry Collector for metrics collection, either Grafana Alloy the upstream collector, create a values.yml with the following configuration:

preset: network

env:
  OTEL_EXPORTER_OTLP_ENDPOINT: your-otlp-endpoint:4318

Install and run Beyla network metrics for Asserts

Run the following helm commands to add the grafana repository and install and run beyla with your configuration for network metrics:

helm repo add grafana https://grafana.github.io/helm-charts
helm install beyla --create-namespace -n beyla -f values.yaml grafana/beyla

Observe your services in Asserts

Finally, navigate to Asserts in Grafana Cloud and view your instrumented services.

Beyla Network Metrics configuration options

Wed, 15 Apr 2026 16:46:57 +0000

Beyla Network Metrics configuration options

Network metrics are configured under the network property of the Beyla Configuration YAML file or with a set of environment variables prefixed as BEYLA_NETWORK_.

Example YAML:

network:
  enable: true
  cidrs:
    - 10.10.0.0/24
    - 10.0.0.0/8
    - 10.30.0.0/16
attributes:
  kubernetes:
    enable: true
  select:
    beyla_network_flow_bytes:
      include:
      - k8s.src.owner.name
      - k8s.src.namespace
      - k8s.dst.owner.name
      - k8s.dst.namespace
      - src.cidr
      - dst.cidr
otel_metrics_export:
  endpoint: http://localhost:4318

In addition to the network YAML section, Beyla configuration requires an endpoint to export the network metrics (in the previous example, otel_metrics_export, but it also accepts a Prometheus endpoint).

Network metrics configuration properties

To enable network metrics, add one of the following features to the first-level metrics section:

network enables the beyla_network_flow_bytes metric: the number of bytes between two endpoints of your cluster
network_inter_zone enables beyla_network_inter_zone_bytes metric: the number of bytes between different availability zones in your Cloud cluster

Caution
The beyla_network_inter_zone_bytes specification is currently in experimental and only available for Kubernetes cluster. The specification is not final and future version of Beyla may introduce breaking changes.

YAML	Environment variable	Type	Default
`source`	`BEYLA_NETWORK_SOURCE`	string	`socket_filter`

Specifies the Linux Kernel feature used to source the network events Beyla reports.

The available options are: tc and socket_filter.

When tc is used as an event source, Beyla uses the Linux Traffic Control ingress and egress filters to capture the network events, in a direct action mode. This event source mode assumes that no other eBPF programs are attaching to the same Linux Traffic Control interface, in direct action mode. For example, the Cilium Kubernetes CNI uses the same approach, therefore if you have Cilium CNI installed in your Kubernetes cluster, configure Beyla to capture the network events with the socket_filter mode.

When socket_filter is used as an event source, Beyla installs an eBPF Linux socket filter to capture the network events. This mode doesn’t conflict with Cilium CNI or other eBPF programs, which use the Linux Traffic Control egress and ingress filters.

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.

The attribute as a function of the source and destination IP addresses. If an IP address does not match any address here, the attributes won’t be set. If an IP address 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 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:

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 address 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 Beyla should 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) Beyla should 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)

The interface names 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`

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
`protocols`	`BEYLA_NETWORK_PROTOCOLS`	[]string	(empty)

If set, Beyla drops any network flow whose reported Internet Protocol is not in this list.

The accepted values are defined in the Linux enumeration of Standard well-defined IP protocols, and can be: TCP, UDP, IP, ICMP, IGMP, IPIP, EGP, PUP, IDP, TP, DCCP, IPV6, RSVP, GRE, ESP, AH, MTP, BEETPH, ENCAP, PIM, COMP, L2TP, SCTP, UDPLITE, MPLS, ETHERNET, RAW

YAML	Environment variable	Type	Default
`exclude_protocols`	`BEYLA_NETWORK_EXCLUDE_PROTOCOLS`	[]string	(empty)

If set, Beyla drops any network flow whose reported Internet Protocol is in this list.

If the protocols/BEYLA_NETWORK_PROTOCOLS list is already set, this property is ignored.

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

Note
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)

The rate at which packets should be sampled and sent to the target collector. For example, 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 to standard output. Note, this might generate a lot of output.

Network metrics on Grafana Labs

Beyla network metrics quickstart

Beyla network metrics quickstart

Deploy Beyla with network metrics

Example configuration

Export OpenTelemetry metrics

Select metrics attributes to reduce cardinality

Group IP addresses by CIDR

Measure traffic between Cloud availability zones

Measure traffic between Cloud availability zones

Add src.zone and dst.zone attributes to regular network metrics

Use the beyla.network.inter.zone metric

PromQL queries to measure inter-zone traffic

Set up Beyla network metrics in Kubernetes with Helm for Asserts

Set up Beyla network metrics in Kubernetes with Helm for Asserts

Prerequisites

Configuration for Kubernetes monitoring

Configure for OpenTelemetry Collector

Install and run Beyla network metrics for Asserts

Observe your services in Asserts

Beyla Network Metrics configuration options

Beyla Network Metrics configuration options

Network metrics configuration properties

Add `src.zone` and `dst.zone` attributes to regular network metrics

Use the `beyla.network.inter.zone` metric