Skip to content
LoggerheadDocs
Download

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

Section titled “Before you start”
  • Loggerhead is open.
  • Docker Desktop or OrbStack runs on this Mac.
  • You know the effective port. Open Collectors → Local OTLP receiver → Connection and copy the gRPC port. See Ports and the effective port.

Step 1: write the branch config

Section titled “Step 1: write the branch config”

Save this file as branch-collector.yaml.

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
  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

Section titled “Step 2: start the branch”

Replace 4317 with the effective port.

Terminal window
docker run -d --name loggerhead-branch \
  -p 15317:4317 -p 15318:4318 \
  -e LOGGERHEAD_COLLECTOR_ID=docker-branch-1 \
  -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 its own ports as 15317 and 15318 on the Mac. Point your apps at those ports. Do not publish 4317 and 4318, because the root asks for them.

The same branch in Compose

Section titled “The same branch in Compose”
compose.yaml
services:
  loggerhead-branch:
    image: otel/opentelemetry-collector:latest
    command: ["--config=file:/etc/otelcol/config.yaml"]
    ports:
      - "15317:4317"
      - "15318:4318"
    environment:
      LOGGERHEAD_COLLECTOR_ID: docker-branch-1
      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

Section titled “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

Section titled “Check the branch”
  1. docker logs loggerhead-branch shows no export error.
  2. Send one test record to http://127.0.0.1:15318/v1/logs.
  3. The record appears on the Logs page. The branch appears on the Collectors page as docker-branch-1.