#When to Use eBPF Instrumentation

eBPF is appropriate when:

• You cannot modify application code (compiled binaries, vendor-provided containers)
• You need immediate instrumentation during incident response
• The application uses standard HTTP/HTTPS/gRPC protocols
• Infrastructure-level visibility (request rates, latencies, error rates) is sufficient

eBPF is not appropriate when:

• You need application-specific context (user IDs, transaction IDs, business metadata)
• You require detailed error messages with stack traces
• The environment does not allow privileged containers

For applications where you control the code and need detailed context, use SDK instrumentation.

For quick visibility into traffic patterns without code changes, eBPF is an useful tool.

#Discovery by Port

The most straightforward method is to specify the port your service listens on:

environment:
  OTEL_EBPF_OPEN_PORT: 5678

This instruments any process listening on port 5678. For multiple services:

environment:
  OTEL_EBPF_OPEN_PORT: "5678,8080,9000"

You can also use the config file:

discovery:
  instrument:
    - open_ports: 5678,8000-899

#Discovery by Executable Name

If you know the process executable path:

discovery:
  instrument:
    - exe_path: /app/my-app

This matches processes where the executable is named my-app. Useful when multiple services run on different ports but only specific executables should be instrumented.

#Discovery Containerized Processes

For targeting only proccess running in a OCI container:

discovery:
  instrument:
    - containers_only: true

#Multiple Discovery Methods

Available discovery methods can be combined and the target process will be instrumented only if it matches all the selectors:

environment:
  instrument:
    - open_ports: 5678,8000-899
    - containers_only: true

#Sampling

Sampling can be configured directly with OpenTelemetry eBPF Instrumentation:

environment:
  OTEL_TRACES_SAMPLER: 'traceidratio'
  OTEL_TRACES_SAMPLER_ARG: '0.1' # 10%

#Endpoint Filtering with OpenTelemetry Collector

The OpenTelemetry Collector provides robust mechanisms for filtering spans based on HTTP attributes such as path or target.

Excluding Specific Routes

The example below drops spans for /health and /metrics endpoints before they are exported to Logfire.

processors:
  filter/drop-low-value-routes:
    traces:
      exclude:
        match_type: regexp
        attributes:
          - key: http.target
            value: ^/health|^/metrics

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [filter/drop-low-value-routes]
      exporters: [otlp]

With this configuration:

• Requests to /health do not reach Logfire
• Requests to /metrics do not reach Logfire
• All other requests are exported normally

Filtering Using Exact Matches

To drop only exact paths:

processors:
  filter/drop-health:
    traces:
      exclude:
        match_type: strict
        attributes:
          - key: http.target
            value: /health

Filtering Using wildcards or Prefixes

To drop all routes under a prefix:

processors:
  filter/drop-internal:
    traces:
      exclude:
        match_type: regexp
        attributes:
          - key: http.target
            value: ^/(health|metrics|ready)

#Enable Trace Printing

To verify the instrumentation is capturing traffic before it reaches Logfire:

environment:
  OTEL_EBPF_TRACE_PRINTER: text

This prints captured spans to the container logs:

docker-compose logs -f obi

You should see output like:

2026/01/30 13:35:17 localhost:5678 172.19.0.1:58574 "GET /hello/world HTTP/1.1" 200 12 "curl/8.16.0" 11.168µs

#Common Issues

No traces appearing:

1. Verify the target service is running: docker-compose ps
2. Check the instrumentation container has host PID access: pid: 'host' is set
3. Verify privileged mode: privileged: true needs to be set
4. Check discovery configuration matches your service (port, executable name, etc.)
5. View instrumentation logs: docker-compose logs obi

Spans visible in logs but not in Logfire:

1. Verify the Logfire token is correct
2. Check the endpoints are correct (logfire-us.pydantic.dev, logfire-eu.pydantic.dev)
3. Ensure the Authorization header includes Bearer prefix
4. Check for export errors in logs: docker-compose logs obi | grep -i error

#What eBPF Cannot Capture

• Application context: User IDs, session tokens, custom business attributes
• Request/response bodies: For security and performance, eBPF does not capture payload data
• Internal function calls: Only network-level operations are visible

#Security Considerations

The instrumentation container requires privileged: true to attach eBPF programs to the kernel. This grants significant access. In production:

1. Run the instrumentation container on a dedicated network segment if possible
2. Use CAP_SYS_ADMIN, CAP_BPF, and CAP_PERFMON capabilities instead of full privileged mode where supported (kernel 5.8+)
3. Monitor the instrumentation container itself for anomalous behavior
4. Restrict access to the docker-compose file containing Logfire credentials

#Platform Compatibility

• Supported: Linux kernel 4.14+
• Recommended: Linux kernel 5.8+ for full feature support
• Not supported: Windows, macOS (eBPF is Linux-specific)
• Container runtimes: Docker, containerd, CRI-O

#Can I use this in Kubernetes?

Yes. The same otel/ebpf-instrument image can run as a DaemonSet in Kubernetes. Service discovery can be based on k8s metadata, for example pods selectors.

#Does this work with HTTPS?

Yes. eBPF observes traffic before TLS termination (at the application level) and after TLS termination (at the load balancer level), depending on where it attaches.

#Can I use this with gRPC?

Yes. gRPC over HTTP/2 is supported. Spans will include gRPC method names and status codes.

#Can I export to multiple backends?

Yes, but not directly through ebpf-instrument. You would need to run an OpenTelemetry Collector that receives from the eBPF instrumentation and fans out to multiple backends.