eBPF requirements and troubleshooting

Fix the most common problems with Better Stack collector on Kubernetes and Docker, starting with what eBPF tracing needs from your hosts.

Required kernel features

Collector requires Linux kernel 5.14 or newer for reliable eBPF-based auto-instrumentation. It relies on BTF, CO-RE, and the eBPF ring buffer (BPF_MAP_TYPE_RINGBUF). Older kernels may work if your distribution has backported these features.

Check if your system supports all the required features with:

Host system Kubernetes Docker
curl -sSL https://telemetry.betterstack.com/api/collector/public/ebpf.sh | bash
kubectl run -i --rm ebpf-check --image=alpine --restart=Never --privileged=true -- sh -c "apk add --no-cache bash wget -q && \
  wget -qO- https://telemetry.betterstack.com/api/collector/public/ebpf.sh | bash"
docker run --rm --privileged alpine:latest sh -c "apk add --no-cache bash wget -q && \
  wget -qO- https://telemetry.betterstack.com/api/collector/public/ebpf.sh | bash"

With eBPF tracing, keep 4 GiB of memory and 4 vCPUs available on each host or Kubernetes node. Without it, 2 GiB of memory and 2 vCPUs are enough.

Your cluster doesn't support all the required features?

Use OpenTelemetry SDK and send traces to Better Stack anyway.

eBPF performance impact

Better Stack collector uses open source eBPF-based instrumentation. eBPF plugs directly into the kernel to generate metrics and traces based on network calls. In some cases, eBPF can increase CPU usage and network latency. For most use-cases and applications the performance impact is negligible or well worth the auto-instrumentation benefits.

Issues with a specific service?

Toggle eBPF for the affected service:

  • Go to Sources → your collector → Configure.
  • Open the Services tab, find your service, and toggle Collect traces.

Traces won't be collected for the service via eBPF-instrumentation.

Cluster-wide performance issues

Seeing elevated CPU load or network latencies across your cluster?
Switch eBPF tracing to a lighter variant to reduce performance impact:

  • Go to Sources → your collector → Configure.
  • Scroll down to What data do you want to collect? and enable Basic distributed tracing.

eBPF tracing will now run significantly faster. Traces might be incomplete.

Disabling eBPF completely

Still experiencing issues? Try these options in order:

  • Disable both Full distributed tracing and Basic distributed tracing. No traces will be produced.
  • Disable Service map & RED metrics.
  • Disable Host metrics.

Well-known issues

  • SignalR WebSocket library experiences connection issues with eBPF enabled.

Tracing Java services

Collector traces the requests your Java services handle without code changes. By default, Java encrypts MySQL connections inside the app, so collector needs Java service tracing to see those requests and queries. Java service tracing also keeps each request in one trace when your service hands work to a thread pool or async code.

Enable Java service tracing

Java service tracing needs Basic distributed tracing or Full distributed tracing, and collector v1.1.46 or newer on every host.

  1. Go to Sources → your collector → Configure → Ingest.
  2. Under What should we monitor with eBPF?, enable Java service tracing.
  3. Click Save & apply.

Turning Java service tracing off?

Disable Java service tracing, then restart your Java services. Java service tracing stays loaded in each service until the service restarts.

Connect traces between services over HTTPS

To keep one trace when your Java services send HTTPS requests to each other, add the OpenTelemetry Java agent to these services. It adds the trace context to each request before Java encrypts it, so the receiving service continues the same trace.

  1. Enable OpenTelemetry in collector.
  2. In Kubernetes, add the inject-java annotation to automatically instrument your services.
  3. Elsewhere, start each service with the agent and send its data to collector.

Conflicts with other tracing solutions

In rare occasions, running the Better Stack collector alongside other tracing solutions, like Sentry or Datadog, can cause conflicts.

A possible symptom is seeing connection errors to services such as Elasticsearch after installing the collector. The service might start returning errors indicating duplicate headers.

Error example
{
  "error": {
    "type": "illegal_argument_exception",
    "reason": "multiple values for single-valued header [traceparent]."
  }
}

In such a case, we recommend to disable tracing in the other monitoring tool to prevent duplicate headers. This ensures that only the Better Stack collector is responsible for injecting the tracing headers.

Why exactly does the conflict occur?

This error occurs because both the collector's eBPF-based instrumentation (OBI) and the other tracing tool are adding a traceparent header. Some services, like Elasticsearch, can strictly enforce the W3C specification and reject requests with multiple traceparent headers.

OBI is designed to prevent this by respecting existing traceparent headers, as seen in the official documentation. However, conflicts can still occur if the other tool doesn't handle existing headers correctly.

Seeing incomplete traces

If you notice incomplete traces, try the following steps:

Restart your services

This ensures the Better Stack collector’s eBPF instrumenters hook into processes correctly.

Remove other tracing agents

Tools like Datadog and Jaeger can conflict with eBPF-based instrumentation.

Disable other eBPF instrumenters

Running more than one eBPF tool at the same time may cause spans to be dropped.

Turn on Java service tracing

Collector needs Java service tracing to trace HTTPS and MySQL requests from Java services, and work they hand to other threads.

Insufficient ServiceAccount permissions in Kubernetes

If you see Kubernetes discovery failed errors, make sure the ServiceAccount used by the Collector can list pods, services, endpoints, and namespaces. The Collector relies on the Kubernetes API to discover workloads and attach metadata to logs, metrics, and traces.

The container name is already in use

In Docker, stop and remove previous collector version:

Stop and remove containers
docker stop better-stack-collector better-stack-collector-host && \
  docker rm better-stack-collector better-stack-collector-host

Older collector versions named the privileged container better-stack-ebpf or better-stack-beyla. Stop and remove those container names instead.

In Docker Swarm, force the upgrade instead.

If you notice errors mentioning Mountpoint '/' has total capacity of X bytes, but configured buffers using mountpoint have total maximum size of Y bytes, adjust the Batching on disk size:

CleanShot 2025-12-04 at 15.59.42@2x.png

Collector allocates three buffers of the given size, which by default totals 9GB. Smaller buffers are less resilient to data loss during transient network failures.

Need help?

Better Stack collector is open source. Report a bug in the GitHub repository, or let us know at hello@betterstack.com.
We're happy to help! 🙏