<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/collectors/ebpf.plugin/ebpfgo.plugin/integrations/ebpf_socket.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/collectors/ebpf.plugin/ebpfgo.plugin/metadata.yaml"
sidebar_label: "eBPF Socket"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Collectors/Operating Systems"
keywords: ['TCP', 'UDP', 'Network monitoring', 'eBPF']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
endmeta-->

# eBPF Socket


<img src="https://netdata.cloud/img/ebpf.jpg" width="150"/>


Plugin: ebpf-go.plugin
Module: socket

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## Overview

Monitor TCP and UDP function calls, bandwidth, errors, and connection counts. Data is exposed through the on-demand `network-protocols` function consumed by the network-viewer.

Attach kprobe or fentry/fexit trampolines to the kernel functions `tcp_sendmsg`, `tcp_cleanup_rbuf`, `tcp_connect` (IPv4 and IPv6), `tcp_close`, `udp_sendmsg`, and `udp_recvmsg`. Per-cycle deltas and byte counts are computed in userspace from the BPF map snapshots.

This collector is only supported on the following platforms:

- Linux

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

The plugin needs setuid because it loads data inside the kernel. Netdata sets the necessary permissions during installation.

### Default Behavior

#### Auto-Detection

The plugin checks kernel compilation flags (CONFIG_KPROBES, CONFIG_BPF, CONFIG_BPF_SYSCALL, CONFIG_BPF_JIT), presence of BTF files, and the configured object flavor to decide which eBPF program will be attached.

#### Limits

The default configuration for this integration does not impose any limits on data collection.

#### Performance Impact

This thread adds overhead every time a monitored kernel TCP or UDP function is called. The estimated additional period of time is between 90-200ns per call on kernels that do not have BTF technology.

## Setup


### Prerequisites

#### Compile kernel

Check if your kernel was compiled with necessary options (CONFIG_KPROBES, CONFIG_BPF, CONFIG_BPF_SYSCALL, CONFIG_BPF_JIT) in `/proc/config.gz` or inside /boot/config file. Some cited names can be different according to the preferences of Linux distributions.
When you do not have options set, it is necessary to get the kernel source code from https://kernel.org or a kernel package from your distribution, this last is preferred. The kernel compilation has a well defined pattern, but distributions can deliver their configuration files
with different names.

Now follow steps:
1. Copy the configuration file to /usr/src/linux/.config.
2. Select the necessary options: make oldconfig
3. Compile your kernel image: make bzImage
4. Compile your modules: make modules
5. Copy your new kernel image for boot loader directory
6. Install the new modules: make modules_install
7. Generate an initial ramdisk image (`initrd`) if it is necessary.
8. Update your boot loader



### Configuration

#### Options

The `socket` option in section `[ebpf programs]` controls whether the module is loaded.
Per-module overrides (`update every`, `maps per core`, `btf path`, `ebpf object flavor`, `pid table size`, `socket monitoring table size`, `udp connection table size`) belong in `ebpf.d/socket.conf`.


<details open><summary>Config options</summary>



| Option | Description | Default | Required |
|:-----|:------------|:--------|:---------:|
| socket | Enable (`yes`) or disable (`no`) the socket monitoring module. | no | no |
| update every | Data collection frequency in seconds. | 10 | no |
| maps per core | When enabled (`yes`), the plugin allocates one BPF hash table per CPU core instead of a single shared table. Improves throughput on multi-core systems; ignored on kernels older than 4.15. | yes | no |
| btf path | Path to the directory containing BTF files used for CO-RE (Compile Once, Run Everywhere) loading. | /sys/kernel/btf | no |
| ebpf object flavor | Select the BPF object flavor. Available values are `arena`, `buffer ring` (also accepted as `buffer`), and `legacy` (also accepted as `tracing`). The collector falls back to the next available flavor when the requested one is not supported by the running kernel. | buffer | no |
| pid table size | Maximum number of PIDs tracked in the per-PID SHM segment shared with `apps.plugin` and `cgroups.plugin`. Increase on hosts with more than 32768 concurrent monitored processes. | 32768 | no |
| socket monitoring table size | Maximum number of connections tracked in the `tbl_nd_socket` BPF hash map (per-PID TCP/UDP bandwidth). Increase on hosts with many concurrent connections; each entry consumes kernel BPF map memory. | 16384 | no |
| udp connection table size | Maximum number of UDP connections tracked in the `tbl_nv_udp` BPF hash map. Increase on hosts with high UDP connection rates. | 4096 | no |


</details>



#### via File

The configuration file name for this integration is `ebpf.d.conf`.


You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

```bash
cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config ebpf.d.conf
```

##### Examples
There are no configuration examples.



## Alerts

There are no alerts configured by default for this integration.



## Metrics

Metrics grouped by *scope*.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

This module attaches to kernel TCP/UDP functions and publishes host-level TCP/UDP activity
through the on-demand `network-protocols` function (FUNCTIONGLOBAL) consumed by the
network-viewer. Per-cgroup and per-service socket activity is exported through the
eBPFGo shared-memory path consumed by `cgroups.plugin`.

> **Migration note** — Per-host and per-app charts published by prior versions of `ebpf.plugin`
> are not republished. The following are permanently removed; use the `network-protocols` function
> in network-viewer as a replacement.
>
> Removed per-host charts: `ip.inbound_conn`, `ip.tcp_outbound_conn`, `ip.tcp_functions`,
> `ip.total_tcp_bandwidth`, `ip.tcp_error`, `ip.tcp_retransmit`, `ip.udp_functions`,
> `ip.total_udp_bandwidth`, `ip.udp_error`.
>
> Removed per-app charts: `app.ebpf_call_tcp_v4_connection`, `app.ebpf_call_tcp_v6_connection`,
> `app.ebpf_sock_total_bandwidth`, `app.ebpf_call_tcp_sendmsg`, `app.ebpf_call_tcp_cleanup_rbuf`,
> `app.ebpf_call_tcp_retransmit`, `app.ebpf_call_udp_sendmsg`, `app.ebpf_call_udp_recvmsg`.
>
> **Configuration changes from `network.conf`** — The `network.conf` file has been replaced by
> `socket.conf`. The following defaults changed silently:
>
> - `maps per core` changed from `no` to `yes`. Per-core BPF maps use more memory but reduce
>   contention on multi-core systems. To restore the previous behaviour add `maps per core = no`
>   to `socket.conf`.
> - `ebpf co-re tracing` changed from `probe` (kprobe/legacy BPF) to `trampoline` (auto-detected).
>   To force kprobes add `ebpf co-re tracing = probe` to `socket.conf`.
> - The `[network connections]` and `[service name]` sections from `network.conf` have no
>   equivalent in `socket.conf` and are not read; any per-port service name overrides are lost.

### `network-protocols` function columns

The `network-protocols` function returns a table with one row per transport protocol and the
following columns:

| Column | Description |
|:-------|:------------|
| Transport | Protocol name (TCP or UDP) |
| Family | IP family (IPv4+IPv6 combined) |
| Received | Segments or datagrams received per second |
| Sent | Segments or datagrams sent per second |
| Errors | Send/receive errors per second |
| ConnActive | Active connections opened per second |
| ConnEstablished | Currently established connections |
| ConnPassive | Passive connections opened per second |
| ConnReset | Reset connections per second |
| SegsTotal | Total segments per second |
| SegsRetransmitted | Retransmitted segments per second |
| DatagramsNoPort | Datagrams with no destination port per second |



### Per eBPF Socket instance

All data is delivered through the on-demand `network-protocols` function consumed by network-viewer; no traditional Netdata charts are published for this scope.

This scope has no labels.

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
