---
title: "eBPF Traffic Collection | Speedscale Docs"
description: "Explore how Speedscale utilizes eBPF for efficient traffic collection in Kubernetes, capturing plaintext and TLS traffic without application changes."
canonical: "https://docs.speedscale.com/reference/ebpf-traffic-collection/"
---

[Documentation index](https://docs.speedscale.com/reference/llms.txt) | [Markdown](https://docs.speedscale.com/reference/ebpf-traffic-collection/index.md) | [Canonical page](https://docs.speedscale.com/reference/ebpf-traffic-collection/)

# eBPF Traffic Collection

For Kubernetes setup, follow [Kubernetes capture with eBPF and Java Agent](https://docs.speedscale.com/guides/capture/kubernetes/). Use this reference for detailed node requirements, runtime permissions, TLS support, and limitations.

<a id="what-is-ebpf"></a>

## What is eBPF?

eBPF (extended Berkeley Packet Filter) is a Linux kernel technology that allows running sandboxed programs in the kernel without changing kernel source code or loading kernel modules. Many Kubernetes networking tools such as [Cilium](https://cilium.io/) use eBPF for efficient, low-overhead traffic observation.

<a id="system-requirements"></a>

## System Requirements

Before enabling eBPF capture, confirm your nodes meet the kernel and architecture baseline below. Nodes that fall outside these ranges are not supported.

*   **`x86_64`:** Linux kernel **5.15 or newer**.
*   **`arm64` / `aarch64`:** Linux kernel **6.0 or newer**. Kernels older than 6.0 are supported on `x86_64` only.
*   **RHEL:** RHEL **9.2 or newer** on both `x86_64` and `arm64`/`aarch64`. Anything prior to 9.2 is incompatible.
*   **BTF (BPF Type Format):** must be enabled in the kernel. BTF provides portable type information that lets the `nettap` probes work across kernel versions without recompilation.
*   **Host access:** when running in Kubernetes, the collector must be able to read host `procfs`, `cgroupv2`, and kernel BTF paths.

<a id="how-speedscale-uses-ebpf"></a>

## How Speedscale Uses eBPF

Speedscale's eBPF collector `nettap` runs as a Kubernetes **DaemonSet** on each node. It attaches lightweight probes to the kernel and to specific user-space libraries to observe network traffic without proxies, sidecars, or application changes.

<a id="plaintext-tcp-traffic"></a>

### Plaintext TCP Traffic

Kernel-level **kprobes** attach to TCP send/receive functions to observe plaintext TCP traffic directly in the kernel's network stack. This captures traffic for any application on the node without needing per-process instrumentation.

<a id="tls-traffic"></a>

### TLS Traffic

See [TLS Traffic Visibility](https://docs.speedscale.com/reference/ebpf-traffic-collection/#tls-traffic-visibility) below for details on how encrypted traffic is captured in plaintext.

<a id="dns-enrichment"></a>

### DNS Enrichment

`nettap` observes DNS traffic in order to build an IP-to-hostname mapping table. This enriches captured traffic with the original hostnames so that traffic is displayed with meaningful service names rather than raw IP addresses. This is particularly useful for non-HTTP protocols where there is no equivalent to the HTTP `Host` header.

<a id="kubernetes-integration"></a>

### Kubernetes Integration

`nettap` runs with `hostNetwork` and `hostPID` enabled, giving it visibility into all pods on the node. It uses this ability along with the Kubernetes API in order to map connections back to specific pods, enriching captured traffic with pod name, namespace, labels, and other metadata.

<a id="tls-traffic-visibility"></a>

## TLS Traffic Visibility

Speedscale captures TLS-encrypted traffic in plaintext, without needing certificates, proxies, or application changes. There are four primary capture mechanisms: uprobes for applications and runtimes using OpenSSL 3.x libraries, uprobes on Go's `crypto/tls`, uprobes on Rust's rustls library, and a Java instrumentation agent for the JVM.

OpenSSL support works for **both** dynamically and statically linked 3.x libraries. Processes that use this will have uprobes attached to OpenSSL read/write functions. This allows data to be captured before being encrypted (writes) and after decryption (reads).

Go applications are instrumented with eBPF uprobes attached to the read/write methods of the standard `crypto/tls` package. The idea is the same as OpenSSL. Support for this requires Go versions **1.18 or newer** and requires binaries to preserve the ELF symbol table, i.e. they must be **unstripped** and built **without** using `-ldflags="-s"`.

Rust applications that use rustls are instrumented at the rustls plaintext read and write boundaries. This requires `nettap` **v0.1.77 or newer** and a Linux ELF binary that retains its symbol table. Do not strip the binary or use link-time optimization that removes or inlines the rustls probe targets. The verified matrix includes rustls 0.23, tokio-rustls 0.26, and Apollo Router 2.17. Rust applications that use OpenSSL 3.x use the OpenSSL capture path instead. See [Rust language support](https://docs.speedscale.com/reference/languages/rust/#ebpf-capture) for build settings and verification steps.

For JVM applications, including Java and Kotlin services, the Java agent captures supported socket and TLS paths inside the JVM. Coverage depends on the transport, TLS provider, and agent version. See [Java agent setup and framework support](https://docs.speedscale.com/reference/java/agent/) for the tested matrix and known gaps, and [Kotlin language support](https://docs.speedscale.com/reference/languages/kotlin/#ebpf-java-agent) for the Kotlin workflow. Loading the agent requires new pods and a JVM restart.

Language/runtime support is tied to the TLS capture mechanism mentioned above, but they all share the same kernel and architecture baseline (see [System Requirements](https://docs.speedscale.com/reference/ebpf-traffic-collection/#system-requirements)). The following have been tested and verified:

| Language | Capture Method | TLS Support | Considerations |
| --- | --- | --- | --- |
| Go | eBPF uprobe (`crypto/tls`) | Native | See above |
| Java | Java instrumentation agent | JSSE hook | Requires `nettap` Java agent (Handled by the Speedscale Operator) |
| [Kotlin](https://docs.speedscale.com/reference/languages/kotlin/#ebpf-java-agent) | Java instrumentation agent | JSSE hook | Same JVM capture path and compatibility matrix as Java |
| [PHP](https://docs.speedscale.com/reference/languages/php/#ebpf-capture) | eBPF uprobe (OpenSSL) | OpenSSL 3.x | PHP cURL or another OpenSSL-backed client |
| .NET | eBPF uprobe (OpenSSL) | OpenSSL 3.x | Linux only; SChannel not supported |
| Python | eBPF uprobe (OpenSSL) | OpenSSL 3.x | Python `ssl` module |
| Node.js | eBPF uprobe (OpenSSL) | OpenSSL 3.x |  |
| [Rust](https://docs.speedscale.com/reference/languages/rust/#ebpf-capture) | eBPF uprobe (rustls or OpenSSL) | rustls 0.23 or OpenSSL 3.x | rustls requires `nettap` v0.1.77+ and an unstripped ELF binary |

<a id="what-this-means-in-practice"></a>

### What This Means in Practice

*   No TLS certificates to install or manage
*   No proxy sidecars to deploy or configure
*   No application code changes or recompilation
*   Full HTTP/HTTPS request and response visibility including headers and bodies

<a id="runtime-requirements"></a>

## Runtime Requirements

Beyond the [System Requirements](https://docs.speedscale.com/reference/ebpf-traffic-collection/#system-requirements), `nettap` needs specific Linux capabilities and host-level visibility to load its probes and see traffic. It does not run as root or as a privileged container: the capture container runs as a non-root user (UID 2102) and carries only the capabilities listed below, granted through file capabilities on the executable. The container sets `allowPrivilegeEscalation: true` because Linux `no_new_privs` would otherwise prevent the executable from acquiring those capabilities. The container remains non-root with `privileged: false`.

<a id="capabilities"></a>

### Capabilities

Speedscale's eBPF collection uses two runtime components with different capability requirements: the `nettap` capture container needs the eBPF and cross-process inspection capabilities, while the ingest/proxy side only needs raw socket access.

| Component | Capability | Purpose |
| --- | --- | --- |
| `nettap` capture | `CAP_BPF` | Load eBPF programs and create/manage BPF maps, including ring buffers and hash maps |
| `nettap` capture | `CAP_PERFMON` | Attach kprobes, kretprobes, uprobes, and fentry/fexit programs |
| `nettap` capture | `CAP_NET_ADMIN` | Perform network-related BPF operations and read kernel socket state used for flow resolution |
| `nettap` capture | `CAP_SYS_ADMIN` | Access kernel BTF and handle namespace-related operations that still require a broad capability |
| `nettap` capture | `CAP_SYS_PTRACE` | Inspect other processes via `/proc/<pid>/maps` and `/proc/<pid>/root` to find TLS libraries and attach cross-process uprobes |
| `nettap` capture | `CAP_SYS_RESOURCE` | Lift `RLIMIT_MEMLOCK` so BPF maps can allocate enough locked memory |
| ingest/proxy | `CAP_NET_RAW` | Open raw sockets for low-level packet inspection and forwarding |

<a id="kubernetes-deployment"></a>

### Kubernetes Deployment

`nettap` runs as a **DaemonSet** with:

*   `hostNetwork: true` - visibility into host-level network traffic to capture traffic for any pod scheduled on the node
*   `hostPID: true` - ability to discover and attach probes to application processes for any pod scheduled on the node
*   a non-root security context: `runAsUser: 2102`, `runAsGroup: 2102`, `fsGroup: 2102`, `privileged: false`, `allowPrivilegeEscalation: true`, all capabilities dropped except the set above
*   read-only hostPath mounts of `/proc`, `/sys`, `/sys/fs/cgroup`, and `/var/run/netns` for process discovery, probe attachment, BTF access, and namespace resolution

On OpenShift, the chart detects the `security.openshift.io/v1` API group and automatically creates a `speedscale-nettap` SecurityContextConstraints granting exactly this contract; see the [OpenShift installation guide](https://docs.speedscale.com/getting-started/installation/install/openshift/#ebpf) for details.

For operator RBAC, admission webhook, and certificate requirements, see [Kubernetes Security Requirements](https://docs.speedscale.com/security/kubernetes-permissions/).

<a id="installation"></a>

## Installation

Helm-restricted environments

The eBPF collector is installed as Kubernetes resources, so Helm does not need to run in the cluster. You can render the Speedscale chart to plain YAML with `helm template` and manage the result directly or as a Kustomize base; see the [GitOps installation example](https://docs.speedscale.com/getting-started/installation/install/kubernetes-operator/?method=gitops#install-method).

If your organization cannot use Helm tooling at all, [contact Speedscale Support](mailto:support@speedscale.com), ask in the [Speedscale Community](https://slack.speedscale.com/), or reach out to your account team. We can help create Kustomize-compatible or other custom manifests with the required eBPF DaemonSet, RBAC, configuration, and cluster-specific settings.

<a id="enabling-via-helm"></a>

### Enabling via Helm

For a new deployment, follow the [standard operator installation](https://docs.speedscale.com/getting-started/installation/install/kubernetes-operator/) first. Its Helm and manifest examples enable eBPF; the speedctl method links to the configuration below.

For an existing installation, add the following settings to the values file you keep for the release, preserving its API key reference, cluster name, and platform overrides. If you installed with `speedctl install` or `--set` flags and have no values file, export the current values first with `helm -n speedscale get values speedscale-operator -o yaml > current-values.yaml`:

```yaml
ebpf:
  enabled: true
  configuration:
    capture:
      targets:
        - name: my-service
          namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: my-namespace
          podSelector:
            matchLabels:
              app: my-service
```

Apply the updated values following [Upgrade flow](https://docs.speedscale.com/reference/helm/#upgrade-flow), using the edited values file with `helm upgrade`.

You can define multiple targets to capture traffic from different services or namespaces. See the [Helm Values reference](https://docs.speedscale.com/reference/helm/) for the full list of eBPF configuration options.

<a id="enabling-via-annotation"></a>

### Enabling via Annotation

Follow [Kubernetes capture with eBPF and Java Agent](https://docs.speedscale.com/guides/capture/kubernetes/#enable-capture-on-the-workload) to set workload annotations, configure port exclusions, add the Java Agent, disable capture, and preserve settings across redeploys. Annotation-based targeting requires the collector to be enabled and running.

<a id="verifying-installation"></a>

### Verifying Installation

Use the [capture verification steps](https://docs.speedscale.com/guides/capture/kubernetes/#verify-capture) to check collector readiness on the workload's nodes, Java Agent injection, and complete captured request/response pairs.

<a id="limitations"></a>

## Limitations

*   **Go binaries must not be stripped** - Go native TLS capture requires preserving the ELF symbol table. Binaries built with `-ldflags="-s"` or otherwise stripped will not have TLS traffic captured. Plaintext TCP traffic is still captured.
*   **Mid-stream connections** - Connections already established before `nettap` attaches its probes miss the beginning of the connection. For simple request/response protocols like HTTP/1.1, later requests on the connection are still captured normally. For multiplexed protocols like HTTP/2 and gRPC, `nettap` needs the start of the stream to parse it, so connections joined mid-stream can't be reassembled and aren't captured until the application opens a new connection.
*   **TCP only** - `nettap` captures TCP traffic only. UDP is only captured for DNS resolution (port 53).
*   **OpenSSL version** - TLS capture via uprobes is limited to OpenSSL 3.x. Applications using older OpenSSL versions, BoringSSL, or LibreSSL will not have TLS traffic captured, though plaintext TCP traffic is still visible.
*   **Rust symbols** - rustls capture requires a Linux ELF binary that retains the rustls function symbols. Stripped binaries and builds whose link-time optimization removes the probe targets fall back to opaque TLS capture. Plaintext TCP traffic remains visible.

<a id="overhead"></a>

## Overhead

eBPF-based collection is designed for minimal production impact. The short version is below; the two pages linked at the end of this section carry the measured numbers and the sizing guidance.

<a id="latency"></a>

### Latency

`nettap` observes traffic passively - it does not sit in the data path. There is no additional network hop, no connection termination, and no proxying. What the probes add is in-kernel work on the syscall path, averaging under two microseconds per TCP send or receive, which does not move request latency out of run-to-run noise.

<a id="cpu"></a>

### CPU

Two distinct costs are worth separating.

The collector's own containers consume CPU for event processing and forwarding, scaling roughly linearly with captured traffic volume. In a controlled benchmark this ranged from 2m at idle to 530m at 1000 QPS across both containers.

The eBPF programs themselves consume kernel CPU that the kernel charges to whichever process made the syscall, not to the collector. That cost is a function of the node's total TCP syscall rate rather than of how much traffic you have configured for capture, because probes attach node-wide and filter inside the kernel.

<a id="memory"></a>

### Memory

The eBPF programs and their maps use a bounded amount of kernel memory and `nettap` avoids unbounded allocations, so memory usage is stable over time.

The collector pod itself is not small. The capture container loads eBPF maps and kernel BTF data at startup and holds roughly 400Mi resident from the moment it is ready, whether or not traffic is flowing. Size the memory request against that baseline rather than against traffic volume.

<a id="where-to-go-next"></a>

### Where to Go Next

*   [Collector Resource Utilization](https://docs.speedscale.com/reference/ebpf-traffic-collection/resource-utilization/) - measured usage by request rate, sizing recommendations, and how to monitor the collector.
*   [Workload Impact](https://docs.speedscale.com/reference/ebpf-traffic-collection/workload-impact/) - what capture does to your applications, how it behaves during canary deployments, what happens when the collector fails, and how to verify all of it yourself.

<a id="sidecar-vs-ebpf"></a>

## Sidecar vs eBPF

Choosing between sidecar-based and eBPF-based traffic collection depends on your environment and requirements.

<a id="when-to-use-ebpf"></a>

### When to Use eBPF

*   You want **frictionless** traffic capture that does not require workload modifications
*   You want **node-level visibility** without per-pod sidecars
*   You need to capture TLS traffic **without managing certificates** or modifying deployments
*   You want to **minimize resource overhead** and avoid sidecar CPU/memory costs

<a id="when-to-use-sidecarsproxies"></a>

### When to Use Sidecars/Proxies

*   Your cluster restricts the elevated permissions required to instrument eBPF probes
*   Your environment requires **per-pod traffic control** with fine-grained policies
*   You are using nodes with **older kernels** that don't meet eBPF requirements
*   You need to capture TLS traffic from applications using TLS libraries not yet supported by the eBPF collector
