Skip to main content

Ingesting Metrics To CtrlB via OpenTelemetry (OTLP)

This document provides instructions for configuring OpenTelemetry Collector and SDKs to forward metrics data to CtrlB instances. OpenTelemetry provides a vendor-neutral standard for observability data collection and export.

Protocol Specifications​

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

  • Ingestion Protocol: OTLP over HTTP (recommended)
  • Endpoint URL: https://<INSTANCE_HOST>/engine/api/default/v1/metrics
  • Supported Formats:
    • JSON
    • Protobuf
  • Content-Type Headers:
    • application/json
    • application/x-protobuf
  • Authentication Method: HTTP Basic Authentication via Authorization header

Basic Configuration​

Create a configuration file named collector.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch: {}

exporters:
  otlphttp:
    endpoint: https://<INSTANCE_HOST>/engine/api/default
    headers:
      Authorization: Basic <API_TOKEN>

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

Application Configuration​

HTTP Protocol Configuration​

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

If using OTEL collector:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://<COLLECTOR_IP>:4318
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://<COLLECTOR_IP>:4318/v1/metrics

If sending directly:

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://<INSTANCE_HOST>/engine/api/default/v1/metrics
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <API_TOKEN>"

Implementation Notes​

CtrlB automatically:

  • Detects content type (JSON vs Protobuf)
  • Decodes OTLP payload
  • Processes metrics using internal handlers

Batch processor improves throughput and reduces overhead.

Validation Procedures​

Service Initialization​

Run OpenTelemetry Collector:

docker run --rm \
  -p 4317:4317 -p 4318:4318 \
  -v $PWD/collector.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector-contrib:latest
  • Ensure metrics are being sent to the Collector from an instrumented application or configured receiver
  • Verify the Collector is exporting metrics to CtrlB via the configured exporter

Verification Process​

  • Access CtrlB dashboard
  • Filter metrics by service or resource attributes
  • Verify data within last few minutes

Troubleshooting Guide​

Authentication Errors​

HTTP 401 Unauthorized

  • Validate Authorization header
  • Confirm API token encoding

Content-Type Issues​

Invalid Payload Format

Ensure correct headers:

  • application/json
  • application/x-protobuf

Endpoint Errors​

HTTP 404

Verify endpoint:

/engine/api/default/v1/metrics

Decode Errors​

  • JSON parsing failures -> invalid payload
  • Protobuf decode failures -> mismatched encoding

Performance Issues​

  • Enable batch processor
  • Tune batch size and timeout
  • Scale Collector resources