Telemetry

Gotenberg integrates OpenTelemetry for distributed tracing, metrics export, and structured log shipping. All three signals are configured via standard OTEL environment variables.

Traces

Every HTTP request creates a server span. External tool calls (Chromium, LibreOffice, QPDF, pdfcpu, PDFtk, ExifTool) and outbound HTTP calls (webhooks, download-from) create child spans with client semantics. Trace context propagates to outbound requests via W3C Trace Context headers.

Configure tracing with standard OTEL environment variables:

Environment variable	Description	Default
`OTEL_TRACES_EXPORTER`	Trace exporter. Options: `none`, `otlp`, `jaeger`, `zipkin`.	`none`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP endpoint for all signals (traces, metrics, logs).	None
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	OTLP endpoint specifically for traces. Overrides the generic endpoint.	None
`OTEL_EXPORTER_OTLP_PROTOCOL`	OTLP transport protocol. Options: `grpc`, `http/protobuf`.	`grpc`
`OTEL_EXPORTER_OTLP_HEADERS`	Headers to send with OTLP requests (e.g., `Authorization=Bearer token`).	None
`OTEL_SERVICE_NAME`	Logical service name attached to all telemetry.	`gotenberg`

compose.yaml
services:
  gotenberg:
    image: gotenberg/gotenberg:8
    environment:
      OTEL_SERVICE_NAME: "gotenberg"
      OTEL_TRACES_EXPORTER: "otlp"
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"

  otel-collector:
    image: otel/opentelemetry-collector-contrib
    # Configure your collector pipeline as needed.

Metrics

HTTP server metrics (request count, duration, size) follow OTEL semantic conventions. Module-specific metrics (conversion duration, output size, queue size, restarts) are exposed as OTEL observable gauges.

Configure metrics export with standard OTEL environment variables:

Environment variable	Description	Default
`OTEL_METRICS_EXPORTER`	Metrics exporter. Options: `none`, `otlp`, `prometheus`.	`none`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP endpoint for all signals (traces, metrics, logs).	None
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	OTLP endpoint specifically for metrics. Overrides the generic endpoint.	None

Migrating from Prometheus

The Prometheus metrics endpoint is deprecated as of Gotenberg 8.29.0. Replace it with OTEL-based metrics export.

Option 1: OTLP to a Prometheus-compatible backend

Send metrics via OTLP to a collector that writes to Prometheus, Mimir, or any compatible backend:

compose.yaml
services:
  gotenberg:
    image: gotenberg/gotenberg:8
    environment:
      OTEL_METRICS_EXPORTER: "otlp"
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"

  otel-collector:
    image: otel/opentelemetry-collector-contrib
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml

otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  prometheusremotewrite:
    endpoint: "http://prometheus:9090/api/v1/write"

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheusremotewrite]

Option 2: Built-in Prometheus exporter

Expose a Prometheus-compatible scrape endpoint directly from Gotenberg via the OTEL SDK. By default, metrics are served at localhost:9464/metrics.

compose.yaml
services:
  gotenberg:
    image: gotenberg/gotenberg:8
    ports:
      - "3000:3000"
      - "9464:9464"
    environment:
      OTEL_METRICS_EXPORTER: "prometheus"
      # Optional: customize host and port.
      # OTEL_EXPORTER_PROMETHEUS_HOST: "0.0.0.0"
      # OTEL_EXPORTER_PROMETHEUS_PORT: "9464"

  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

prometheus.yml
scrape_configs:
  - job_name: "gotenberg"
    scrape_interval: 10s
    static_configs:
      - targets: ["gotenberg:9464"]

This is separate from the legacy /prometheus/metrics route and does not require the Prometheus module flags.

Logs

Gotenberg uses slog-based structured logging. An OTEL log bridge exports logs to configured OTEL backends alongside stdout output.

Configure log export with standard OTEL environment variables:

Environment variable	Description	Default
`OTEL_LOGS_EXPORTER`	Logs exporter. Options: `none`, `otlp`.	`none`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP endpoint for all signals (traces, metrics, logs).	None
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	OTLP endpoint specifically for logs. Overrides the generic endpoint.	None

Stdout Configuration

The following flags control stdout log output. See the Logging configuration for the full list.

Flag	Environment variable	Description	Default
--log-std-format	LOG_STD_FORMAT	Specify the format of logging. Options: auto, json, text.	auto
--log-std-enable-gcp-fields	LOG_STD_ENABLE_GCP_FIELDS	Use GCP-compatible field names (time, message, severity).	false

warning

As of Gotenberg 8.29.0, --log-format has been deprecated in favor of --log-std-format, and --log-enable-gcp-fields has been deprecated in favor of --log-std-enable-gcp-fields.

Telemetry Control

Suppress telemetry (traces, metrics, logs) on high-frequency system routes to reduce noise. All default to true (disabled).

Flag	Environment variable	Description	Default
--api-correlation-id-header	API_CORRELATION_ID_HEADER	Header name for identifying requests.	Gotenberg-Trace
--api-disable-root-route-telemetry	API_DISABLE_ROOT_ROUTE_TELEMETRY	Disable telemetry for the root route.	true
--api-disable-debug-route-telemetry	API_DISABLE_DEBUG_ROUTE_TELEMETRY	Disable telemetry for the debug route.	true
--api-disable-version-route-telemetry	API_DISABLE_VERSION_ROUTE_TELEMETRY	Disable telemetry for the version route.	true
--api-disable-health-check-route-telemetry	API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY	Disable telemetry for the health check route.	true
--prometheus-disable-route-telemetry	PROMETHEUS_DISABLE_ROUTE_TELEMETRY	Disable telemetry for the Prometheus metrics route.	true

warning

As of Gotenberg 8.29.0, --api-trace-header has been deprecated in favor of --api-correlation-id-header, and --api-disable-health-check-logging has been deprecated in favor of --api-disable-health-check-route-telemetry.

Example

A complete Docker Compose setup with Gotenberg exporting traces, metrics, and logs to an OTEL Collector:

compose.yaml
services:
  gotenberg:
    image: gotenberg/gotenberg:8
    ports:
      - "3000:3000"
    environment:
      OTEL_SERVICE_NAME: "gotenberg"
      OTEL_TRACES_EXPORTER: "otlp"
      OTEL_METRICS_EXPORTER: "otlp"
      OTEL_LOGS_EXPORTER: "otlp"
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"

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

otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  # Replace with your preferred backend (Jaeger, Grafana Cloud, Datadog, etc.).
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]
    logs:
      receivers: [otlp]
      exporters: [debug]

Traces​

Metrics​

Migrating from Prometheus​

Logs​

Stdout Configuration​

Telemetry Control​

Example​