Your cluster doesn't support all the required features?
Use OpenTelemetry SDK and send traces to Better Stack anyway.
Fix the most common problems with Better Stack collector on Kubernetes and Docker, starting with what eBPF tracing needs from your hosts.
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:
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.
Use OpenTelemetry SDK and send traces to Better Stack anyway.
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.
Toggle eBPF for the affected service:
Traces won't be collected for the service via eBPF-instrumentation.
Seeing elevated CPU load or network latencies across your cluster?
Switch eBPF tracing to a lighter variant to reduce performance impact:
eBPF tracing will now run significantly faster. Traces might be incomplete.
Still experiencing issues? Try these options in order:
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.
Java service tracing needs Basic distributed tracing or Full distributed tracing, and collector v1.1.46 or newer on every host.
Disable Java service tracing, then restart your Java services. Java service tracing stays loaded in each service until the service restarts.
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.
inject-java annotation to automatically instrument your services. 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.
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.
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.
If you notice incomplete traces, try the following steps:
This ensures the Better Stack collector’s eBPF instrumenters hook into processes correctly.
Tools like Datadog and Jaeger can conflict with eBPF-based instrumentation.
Running more than one eBPF tool at the same time may cause spans to be dropped.
Collector needs Java service tracing to trace HTTPS and MySQL requests from Java services, and work they hand to other threads.
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.
In Docker, stop and remove previous collector version:
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:
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.
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! 🙏
We use cookies to authenticate users, improve the product user experience, and for personalized ads. Learn more.