Skip to main content

Ingesting Traces To CtrlB via OpenTelemetry Collector

This document provides instructions for configuring the OpenTelemetry Collector to forward traces to CtrlB instances. The OpenTelemetry Collector serves as a centralized trace processing and forwarding component.

Protocol Specifications​

The CtrlB platform supports OpenTelemetry Protocol (OTLP) trace ingestion with the following specifications:

  • Ingestion Protocol: OTLP over HTTP (recommended) or gRPC
  • Authentication Method: HTTP Basic Authentication via Authorization: Basic <API_TOKEN>
  • Stream Routing: Data routing accomplished through stream-name: <STREAM_NAME> header
  • Timestamp Processing: Platform automatically derives _timestamp from OTLP event timestamps

Basic Configuration​

Create a configuration file named collector.yaml with the following specification:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318 # OTLP HTTP receiver endpoint
      grpc:
        endpoint: 0.0.0.0:4317 # OTLP gRPC receiver endpoint (optional)

processors:
  batch: {}

exporters:
  otlphttp:
    endpoint: http://<INSTANCE_HOST>/api/default
    headers:
      Authorization: Basic <API_TOKEN>
      stream-name: <STREAM_NAME>

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

Deployment Methods​

Container Deployment​

Deploy using Docker:

docker run --rm \
  -p 4317:4317 -p 4318:4318 \
  -v $PWD/collector.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector-contrib:latest

Linux System Service​

  1. Install the OpenTelemetry Collector from https://opentelemetry.io/docs/collector/installation/#linux
  2. Place configuration at /etc/otelcol/config.yaml
  3. Start service: systemctl start otelcol

Application Configuration​

HTTP Protocol Configuration​

Configure OpenTelemetry SDKs with:

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<COLLECTOR_IP>:4318
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://<COLLECTOR_IP>:4318/v1/traces

gRPC Protocol Configuration​

For gRPC transport:

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<COLLECTOR_IP>:4317

Kubernetes DaemonSet Deployment​

For Kubernetes environments:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: otelcol-gateway
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: otelcol-gateway
  template:
    metadata:
      labels:
        app: otelcol-gateway
    spec:
      containers:
        - name: otelcol
          image: otel/opentelemetry-collector-contrib:0.133.0
          args: ["--config=/etc/otelcol/config.yaml"]
          ports:
            - name: otlp-grpc
              containerPort: 4317
            - name: otlp-http
              containerPort: 4318
          volumeMounts:
            - name: config-volume
              mountPath: /etc/otelcol
              readOnly: true
          resources:
            limits:
              memory: "256Mi"
              cpu: "200m"
      volumes:
        - name: config-volume
          configMap:
            name: otelcol-config

Data Validation​

  1. Access your CtrlB instance dashboard
  2. Apply filters for service.name within the previous 5-minute window
  3. Check the Traces view for incoming trace data

Troubleshooting Guide​

Authentication Issues​

HTTP 401 Unauthorized

  • Verify the Authorization header format: Authorization: Basic <API_TOKEN>
  • Confirm API token is properly encoded

Authorization Issues​

HTTP 403 Forbidden

  • Validate the stream-name header value
  • Confirm API token has appropriate stream access

Endpoint Issues​

HTTP 404 on /v1/traces

  • Ensure endpoint URL format is https://<INSTANCE_HOST> without trailing slash
  • OTLP exporter automatically appends /v1/traces path

Performance Issues​

Degraded Processing

  • Maintain batch processor configuration
  • Enable gzip compression
  • Scale Collector resources based on volume

For information about ingesting logs using the OpenTelemetry Collector, please refer to our OpenTelemetry Collector for Logs documentation.