Docker branch example

A branch is a standard OpenTelemetry Collector that forwards to the root. This example runs the upstream collector image on the same Mac as Loggerhead. The branch receives OpenTelemetry from your apps, drops debug records, stamps its identity, and forwards the rest to the root.

Before you start

Loggerhead is open.
Docker Desktop or OrbStack runs on this Mac.
You know the effective port. Open Collectors → Loggerhead receiver → Connection and copy the gRPC port. See Ports and the effective port.

Step 1: write the branch config

Save this file as branch-collector.yaml.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317      # the BRANCH port inside the container
      http:
        endpoint: 0.0.0.0:4318

processors:
  resource:
    attributes:
      - key: loggerhead.collector.id
        value: ${env:LOGGERHEAD_COLLECTOR_ID}
        action: upsert
      # The environment inside the workspace. Records with this tag land in
      # the Staging database. Leave the key out for Local.
      - key: deployment.environment.name
        value: ${env:LOGGERHEAD_ENVIRONMENT}
        action: upsert
  filter:
    error_mode: ignore
    logs:
      log_record:
        - 'severity_number < SEVERITY_NUMBER_INFO'
  batch: {}

exporters:
  otlp:
    endpoint: ${env:LOGGERHEAD_OTLP_ENDPOINT}   # the ROOT, with the effective port
    tls:
      insecure: true

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [resource, filter, batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [resource, batch]
      exporters: [otlp]
    traces:
      receivers: [otlp]
      processors: [resource, batch]
      exporters: [otlp]

Step 2: start the branch

Replace 4317 with the effective port.

docker network create loggerhead-net   # once

docker run -d --name loggerhead-branch \
  --network loggerhead-net \
  -e LOGGERHEAD_COLLECTOR_ID=docker-branch-1 \
  -e LOGGERHEAD_ENVIRONMENT=staging \
  -e LOGGERHEAD_OTLP_ENDPOINT=host.docker.internal:4317 \
  -v "$PWD/branch-collector.yaml:/etc/otelcol/config.yaml:ro" \
  otel/opentelemetry-collector:latest \
  --config=file:/etc/otelcol/config.yaml

The branch publishes no port on the Mac. It listens on 4317 and 4318 inside the network only. Start your apps on loggerhead-net and point them at loggerhead-branch:4317.

If an application on the Mac itself must reach the branch, add -p 15317:4317 to the command. Do not publish 4317 and 4318, because the root asks for them.

The same branch in Compose

services:
  loggerhead-branch:
    image: otel/opentelemetry-collector:latest
    command: ["--config=file:/etc/otelcol/config.yaml"]
    # No published port. Containers on this network send to loggerhead-branch:4317.
    expose:
      - "4317"
      - "4318"
    environment:
      LOGGERHEAD_COLLECTOR_ID: docker-branch-1
      LOGGERHEAD_ENVIRONMENT: staging
      LOGGERHEAD_OTLP_ENDPOINT: host.docker.internal:4317   # confirm the effective port
    volumes:
      - ./branch-collector.yaml:/etc/otelcol/config.yaml:ro

Collect every container’s logs instead

Use the contrib image and mount the Docker socket read-only. The filelog and docker_stats receivers are in the contrib image only. The app does not open the Docker socket itself, so the branch is the way to read container logs.

Check the branch

docker logs loggerhead-branch shows no export error.
Send one test record from the network: docker run --rm --network loggerhead-net curlimages/curl -X POST -H 'Content-Type: application/json' -d @record.json http://loggerhead-branch:4318/v1/logs.
The record appears on the Logs page. The branch appears on the Collectors page as docker-branch-1.