Network Topology

Port Reference

Network Zone Design

BizFirst Observe components should be isolated in a dedicated observability network zone. This prevents accidental access to storage backends and limits the blast radius of a compromised service:

Zone: Application Network

BizFirstGO services (ProcessEngine, EdgeStream, Octopus, etc.) reside here. They communicate outbound to the OTel Collector's OTLP ports (4317/4318). No observability storage backend should be directly reachable from this zone.

Zone: Observability Network (Internal)

The OTel Collector, Loki, Prometheus, Tempo, Alertmanager, Node Exporter, and cAdvisor reside here. This zone is not accessible from the public internet. Grafana queries these backends from within this zone.

Zone: Management Network (External via Reverse Proxy)

Only Grafana (port 3000) is exposed externally, typically behind a reverse proxy (nginx/Traefik) that enforces TLS and authentication. The reverse proxy forwards requests to Grafana in the observability network.

# Docker Compose network configuration
networks:
  app-network:          # BizFirstGO services
    driver: bridge
  observe-network:      # Observability components (internal)
    driver: bridge
    internal: true      # No outbound internet access
  mgmt-network:         # Grafana external access
    driver: bridge

services:
  otel-collector:
    networks:
      - app-network     # Receives from services
      - observe-network # Exports to backends

  loki:
    networks: [observe-network]

  prometheus:
    networks: [observe-network]

  tempo:
    networks: [observe-network]

  grafana:
    networks:
      - observe-network # Queries backends
      - mgmt-network    # Accessible from outside
    ports:
      - "3000:3000"

Protocol Details

OTLP/gRPC (Preferred)

The preferred protocol for telemetry export. OTLP/gRPC uses HTTP/2 multiplexing, which means a single TCP connection can carry multiple concurrent export streams. This is more efficient than HTTP/1.1 for high-throughput telemetry. The connection is long-lived — the SDK maintains a persistent gRPC channel to the Collector.

OTLP/HTTP (Fallback)

Used when gRPC is not available (e.g., browser-side telemetry, environments where HTTP/2 is blocked by a proxy). OTLP/HTTP uses binary Protobuf encoding over HTTP/1.1 POST requests. It is slightly less efficient but functionally equivalent.

TLS Configuration

# otel-collector-config.yaml — TLS for production
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        tls:
          cert_file: /certs/collector.crt
          key_file: /certs/collector.key
          client_ca_file: /certs/ca.crt  # mTLS: require client cert

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: false
      ca_file: /certs/ca.crt