Menu

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Grafana Cloud

Warning

Network metrics is an experimental under development feature, expect breaking changes.

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:

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

YAMLEnvironment variableTypeDefault
enableBEYLA_NETWORK_METRICSbooleanfalse

Enables network metrics reporting in Beyla.

YAMLEnvironment variableTypeDefault
sourceBEYLA_NETWORK_SOURCEstringtc

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.

YAMLEnvironment variableTypeDefault
allowed_attributesBEYLA_NETWORK_ALLOWED_ATTRIBUTES[]stringk8s.src.owner.name, k8s.src.namespace, k8s.dst.owner.name, k8s.dst.namespace, k8s.cluster.name

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 the same owner.

This property won’t filter some meta-attributes such as instance, job, service.instance.id, service_name, telemetry.sdk.*, etc.

See the network metrics documentation for a detailed list of all the available attributes.

Note

Select carefully the reported attributes, as some attributes might greatly increase the cardinality of your metrics. Setting this value to list only the attributes you really need is highly recommended.

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
YAMLEnvironment variableTypeDefault
cidrsBEYLA_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:

sh
BEYLA_NETWORK_CIDRS=10.0.0.0/8,192.168.0.0/16
YAMLEnvironment variableTypeDefault
agent_ipBEYLA_NETWORK_AGENT_IPstring(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).

YAMLEnvironment variableTypeDefault
agent_ip_ifaceBEYLA_NETWORK_AGENT_IP_IFACEstringexternal

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.

YAMLEnvironment variableTypeDefault
agent_ip_typeBEYLA_NETWORK_AGENT_IP_TYPEstringany

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.

YAMLEnvironment variableTypeDefault
interfacesBEYLA_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:

sh
BEYLA_NETWORK_INTERFACES=eth0,eth1,/^veth/
YAMLEnvironment variableTypeDefault
exclude_interfacesBEYLA_NETWORK_EXCLUDE_INTERFACES[]stringlo

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:

sh
BEYLA_NETWORK_EXCLUDE_INTERFACES=lo,/^veth/
YAMLEnvironment variableTypeDefault
protocolsBEYLA_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

YAMLEnvironment variableTypeDefault
exclude_protocolsBEYLA_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.

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

YAMLEnvironment variableTypeDefault
cache_max_flowsBEYLA_NETWORK_CACHE_MAX_FLOWSinteger5000

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.

YAMLEnvironment variableTypeDefault
cache_active_timeoutBEYLA_NETWORK_CACHE_ACTIVE_TIMEOUTduration5s

Specifies the maximum duration that flows are kept in the accounting cache before being flushed for its later export.

YAMLEnvironment variableTypeDefault
directionBEYLA_NETWORK_DIRECTIONstringboth

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.
YAMLEnvironment variableTypeDefault
samplingBEYLA_NETWORK_SAMPLINGinteger0 (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.

YAMLEnvironment variableTypeDefault
print_flowsBEYLA_NETWORK_PRINT_FLOWSbooleanfalse

If set to true, Beyla prints each network flow to standard output. Note, this might generate a lot of output.