OpenTelemetry Integration

Browserless Enterprise supports OpenTelemetry (OTel) for exporting distributed traces, metrics, and logs to any OTLP-compatible backend. OTel is disabled by default with zero runtime overhead. When enabled, the system uses dynamic imports so OTel packages only load if OTEL_ENABLED=true.

Environment Variables

Variable	Description	Default	Notes
OTEL_ENABLED	Master toggle. Set to true to enable OTel instrumentation.	false	Must be the string true
OTEL_TRACES_ENABLED	Export distributed traces.	true (when OTel enabled)	Disable with false to export only metrics/logs
OTEL_METRICS_ENABLED	Export metrics (CPU, memory, session counts).	true (when OTel enabled)
OTEL_LOGS_ENABLED	Bridge application logs to OTel LogRecords via a Winston transport.	false	Set to true to export logs
OTEL_SERVICE_NAME	Service name reported in traces and metrics.	browserless-enterprise	Change to distinguish multiple instances
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector endpoint URL.	(none, required when enabled)	Example: http://collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL	Exporter wire protocol.	http/protobuf	Only http/protobuf is supported. Other values log a warning and fall back to http/protobuf.
OTEL_EXPORTER_OTLP_HEADERS	Authentication headers as comma-separated key=value pairs.	(none)	Example: Authorization=Bearer abc123
OTEL_RESOURCE_ATTRIBUTES	Additional resource attributes as comma-separated key=value pairs.	(none)	Example: deployment.environment=production,service.version=2.86.0
OTEL_METRIC_EXPORT_INTERVAL	Metric export interval in milliseconds.	60000	Lower values increase collector load

Docker Compose Example

services:
  browserless:
    image: registry.browserless.io/browserless/browserless/enterprise:latest
    environment:
      - KEY=your-license-key
      - TOKEN=your-api-token
      - OTEL_ENABLED=true
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
      - OTEL_SERVICE_NAME=browserless-prod
      - OTEL_LOGS_ENABLED=true
    ports:
      - "3000:3000"

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    ports:
      - "4318:4318"
    volumes:
      - ./otel-config.yaml:/etc/otelcol-contrib/config.yaml

Ignored Endpoints

HTTP auto-instrumentation skips /health, /metrics, and /ready to reduce trace noise. These endpoints do not appear in your trace data.

Log Integration

When OTEL_ENABLED=true and OTEL_LOGS_ENABLED=true, the enterprise logger adds an OpenTelemetry Winston transport that bridges application logs into OTel LogRecords. Control log verbosity with the LOG_LEVEL env var (see Configuration Reference).

Protocol Limitation

Only http/protobuf is supported as the exporter protocol. Setting OTEL_EXPORTER_OTLP_PROTOCOL to grpc or other values logs a warning and falls back to http/protobuf.