Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fopentelemetry%2Finstrumentation-options%2Febpf-auto-instrumentation%2Fcollector-receiver.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fopentelemetry%2Finstrumentation-options%2Febpf-auto-instrumentation%2Fcollector-receiver.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.) # OBI as a collector receiver Starting with v0.5.0, OBI can operate as a receiver component inside the OpenTelemetry Collector. This combines OBI's zero-code eBPF instrumentation with the Collector's processing capabilities — enabling tail-based sampling, data filtering, attribute redaction, and multi-backend export in a single binary. ## When to use Collector receiver mode[​](#when-to-use-collector-receiver-mode "Direct link to When to use Collector receiver mode") New in v0.5.0 Use OBI as a Collector receiver when you need: * **Unified telemetry pipeline**: Process traces, metrics, and logs through a single Collector instance. * **Advanced processing**: Apply tail-based sampling, attribute filtering, or data redaction before export. * **Multiple backends**: Export to Coralogix and additional destinations simultaneously. * **Compliance requirements**: Redact sensitive data (PII, credentials) from telemetry before it leaves the node. For simple deployments with a single backend and no processing requirements, the [standard Helm chart deployment](https://docs-docusaurus.kinsta.page/opentelemetry/instrumentation-options/ebpf-auto-instrumentation/getting-started/.md) is simpler and uses fewer resources. ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") * Linux kernel 5.8+ with BTF enabled (or RHEL 4.18 build 348+). * Go 1.25 or later. * OpenTelemetry Collector Builder (`ocb`) installed. * OBI source repository (v0.5.0 or later — examples below use v0.9.0) cloned locally. * Docker or a local C compiler with clang and eBPF headers. ## Build the custom Collector[​](#build-the-custom-collector "Direct link to Build the custom Collector") ### Step 1: Generate eBPF files[​](#step-1-generate-ebpf-files "Direct link to Step 1: Generate eBPF files") Clone the OBI repository and generate the required eBPF bytecode: ``` git clone https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation.git cd opentelemetry-ebpf-instrumentation git checkout v0.9.0 # Using Docker (recommended): make docker-generate # Or locally if you have clang and eBPF headers: # make generate ``` ### Step 2: Create the builder configuration[​](#step-2-create-the-builder-configuration "Direct link to Step 2: Create the builder configuration") Create a `builder-config.yaml` file that includes the OBI receiver alongside your required processors and exporters: ``` dist: name: otelcol-obi description: OpenTelemetry Collector with OBI receiver output_path: ./dist exporters: - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.142.0 - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.142.0 processors: - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.142.0 receivers: - gomod: go.opentelemetry.io/obi v0.9.0 import: go.opentelemetry.io/obi/collector providers: - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.18.0 - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.18.0 - gomod: go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.18.0 replaces: - go.opentelemetry.io/obi => /path/to/opentelemetry-ebpf-instrumentation ``` Update the `replaces` path to point to your local OBI repository clone. ### Step 3: Build the Collector binary[​](#step-3-build-the-collector-binary "Direct link to Step 3: Build the Collector binary") ``` ocb --config builder-config.yaml ``` The built binary is at `./dist/otelcol-obi`. ## Configure the Collector[​](#configure-the-collector "Direct link to Configure the Collector") Create a `collector-config.yaml` that defines the OBI receiver, processors, and exporters: ``` receivers: obi: open_port: '8080' metrics: features: [network, application] processors: batch: timeout: 1s send_batch_size: 1024 exporters: otlp: endpoint: https://:443 headers: Authorization: Bearer ${env:CORALOGIX_PRIVATE_KEY} service: pipelines: traces: receivers: [obi] processors: [batch] exporters: [otlp] metrics: receivers: [obi] processors: [batch] exporters: [otlp] ``` Replace `` with your [Coralogix OpenTelemetry endpoint](https://docs-docusaurus.kinsta.page/integrations/coralogix-endpoints/.md). ### Run the Collector[​](#run-the-collector "Direct link to Run the Collector") The Collector requires elevated privileges for eBPF probe attachment: ``` sudo ./dist/otelcol-obi --config collector-config.yaml ``` Or grant specific capabilities without running as root: ``` sudo setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search,cap_net_raw,cap_perfmon,cap_bpf,cap_checkpoint_restore=ep ./dist/otelcol-obi ./dist/otelcol-obi --config collector-config.yaml ``` ## Deploy on Kubernetes[​](#deploy-on-kubernetes "Direct link to Deploy on Kubernetes") ### Build and push the container image[​](#build-and-push-the-container-image "Direct link to Build and push the container image") ``` FROM alpine:latest RUN apk --no-cache add ca-certificates COPY dist/otelcol-obi /otelcol-obi RUN chmod +x /otelcol-obi ENTRYPOINT ["/otelcol-obi"] ``` ``` docker build -t /otelcol-obi:v0.9.0 . docker push /otelcol-obi:v0.9.0 ``` ### Deploy as a DaemonSet[​](#deploy-as-a-daemonset "Direct link to Deploy as a DaemonSet") ``` apiVersion: apps/v1 kind: DaemonSet metadata: name: otel-collector-obi namespace: monitoring spec: selector: matchLabels: app: otel-collector-obi template: metadata: labels: app: otel-collector-obi spec: hostNetwork: true hostPID: true containers: - name: otel-collector image: /otelcol-obi:v0.9.0 args: - --config=/conf/collector-config.yaml securityContext: privileged: true capabilities: add: - SYS_ADMIN - SYS_PTRACE - NET_RAW - DAC_READ_SEARCH - PERFMON - BPF - CHECKPOINT_RESTORE volumeMounts: - name: config mountPath: /conf - name: sys mountPath: /sys readOnly: true - name: proc mountPath: /host/proc readOnly: true resources: limits: memory: 1Gi cpu: "1" requests: memory: 512Mi cpu: 500m volumes: - name: config configMap: name: otel-collector-config - name: sys hostPath: path: /sys - name: proc hostPath: path: /proc ``` ## Advanced configurations[​](#advanced-configurations "Direct link to Advanced configurations") ### Tail-based sampling[​](#tail-based-sampling "Direct link to Tail-based sampling") Retain all error traces and slow traces while sampling successful traces at a lower rate. Add the tail sampling processor to your builder configuration: ``` # Add to builder-config.yaml processors: processors: - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.142.0 ``` Then configure the sampling policies in your Collector config: ``` processors: tail_sampling: policies: - name: errors type: status_code status_code: status_codes: [ERROR] - name: slow_traces type: latency latency: threshold_ms: 1000 - name: sample_success type: probabilistic probabilistic: sampling_percentage: 5 batch: timeout: 1s service: pipelines: traces: receivers: [obi] processors: [tail_sampling, batch] exporters: [otlp] ``` ### Sensitive data filtering[​](#sensitive-data-filtering "Direct link to Sensitive data filtering") Redact PII and sensitive attributes before export. Add the attributes processor to your builder configuration: ``` # Add to builder-config.yaml processors: processors: - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/attributesprocessor v0.142.0 ``` Then configure redaction rules: ``` processors: attributes: actions: - key: http.url action: delete - key: user.email action: delete - key: credit_card pattern: \d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4} action: hash batch: timeout: 1s service: pipelines: traces: receivers: [obi] processors: [attributes, batch] exporters: [otlp] ``` ## Feature comparison[​](#feature-comparison "Direct link to Feature comparison") | Feature | Standalone OBI | OBI as Collector receiver | | ------------------------------------------ | -------------- | ------------------------- | | eBPF instrumentation | Supported | Supported | | Service discovery | Supported | Supported | | Traces and metrics collection | Supported | Supported | | JSON log enrichment | Supported | Supported | | Collector processors (sampling, filtering) | Not available | Supported | | Multiple export destinations | Limited | Fully supported | | Tail-based sampling | Not available | Supported | | Resource overhead | Lower | Moderate | | Configuration complexity | Simple | More complex | ## Limitations[​](#limitations "Direct link to Limitations") * **Single node scope**: The OBI receiver instruments processes on the local node only. Deploy as a DaemonSet for cluster-wide coverage. * **Privileged access**: eBPF probe attachment requires elevated capabilities (`CAP_SYS_ADMIN`, `CAP_BPF`, `CAP_SYS_PTRACE`, and others). * **Linux only**: eBPF is a Linux kernel technology. Windows and macOS are not supported. * **Restart required**: Changes to OBI receiver configuration require a Collector restart. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Build fails with API incompatibility errors[​](#build-fails-with-api-incompatibility-errors "Direct link to Build fails with API incompatibility errors") Ensure your OBI source and Collector component versions are compatible: 1. Update the OBI repository: `git pull origin main`. 2. Check the versions in OBI's `go.mod` and match them in your `builder-config.yaml`. 3. Verify Go version is 1.25+. ### No telemetry appears[​](#no-telemetry-appears "Direct link to No telemetry appears") 1. Verify the OBI receiver configuration includes the correct `open_port`. 2. Check Collector logs for service discovery: `grep "discovered service" collector.log`. 3. Verify eBPF programs loaded: `bpftool prog show`. ### Permission denied errors[​](#permission-denied-errors "Direct link to Permission denied errors") Ensure the Collector runs with the required capabilities. On Kubernetes, verify the `securityContext` in your DaemonSet spec includes all required capabilities. ### High memory usage[​](#high-memory-usage "Direct link to High memory usage") Limit instrumentation to specific services to reduce telemetry volume: ``` receivers: obi: discovery: instrument: - k8s_pod_labels: app: web-app - exe_path: api-service ``` Adjust batch processor settings: ``` processors: batch: timeout: 200ms send_batch_size: 512 send_batch_max_size: 1024 ```