Skip to main content
Version: 9.x

Telemetry

Follow what Gotenberg does: logs on standard error, and OpenTelemetry traces, metrics and logs for your collector.

Logs​

Gotenberg logs each request with its status, latency and Gotenberg-Trace, as JSON:

{
"ts": 1793561981.9256449,
"level": "info",
"msg": "request handled",
"logger": "api",
"log_type": "access",
"correlation_id": "req-42",
"remote_ip": "fd07:b51a:cc66:1::1",
"host": "localhost:3009",
"uri": "/forms/libreoffice/convert",
"method": "POST",
"path": "/forms/libreoffice/convert",
"referer": "",
"user_agent": "curl/8.7.1",
"status": 200,
"latency": 124050996,
"latency_human": "124.050996ms",
"bytes_in": 6670,
"bytes_out": 11813,
"trace_id": "7ddb493b5d89f659b26c4fa9370d243b",
"span_id": "e15ea573b02a5d50"
}

Each record is one line; it's spread here for reading.

Export to OpenTelemetry​

The image turns the exporters off. Turn them on with the standard OpenTelemetry variables:

compose.yaml
services:
gotenberg:
image: gotenberg/gotenberg:9
environment:
OTEL_TRACES_EXPORTER: otlp
OTEL_METRICS_EXPORTER: otlp
OTEL_LOGS_EXPORTER: otlp
OTEL_EXPORTER_OTLP_ENDPOINT: http://collector:4318

The service is gotenberg, unless OTEL_SERVICE_NAME names it otherwise. A request carrying a W3C traceparent header continues your trace, and every answer carries the trace it belongs to in Traceparent.

The system routes, /health and /version among them, leave no trace by default: see Health.

Sample traces​

Gotenberg records and exports every trace by default. The standard variables tune it: OTEL_TRACES_SAMPLER=parentbased_traceidratio with OTEL_TRACES_SAMPLER_ARG=0.1 keeps one trace in ten. Sampling in the collector instead, on errors and slow requests, keeps the traces you'd want to read.

Scrape with Prometheus​

The Prometheus exporter serves the metrics on port 9464:

compose.yaml
services:
gotenberg:
image: gotenberg/gotenberg:9
environment:
OTEL_METRICS_EXPORTER: prometheus
OTEL_EXPORTER_PROMETHEUS_HOST: 0.0.0.0

Scrape http://gotenberg:9464/metrics. The exporter turns dots into underscores, in names and attributes, and ends a name with its unit or _total: gotenberg.chromium.requests becomes gotenberg_chromium_requests_total, and gotenberg.chromium.conversion.duration becomes gotenberg_chromium_conversion_duration_seconds.

Metrics​

Each engine, chromium and libreoffice, reports the same set:

MetricTypeWhat
gotenberg.<engine>.requestscounterRequests the engine handled.
gotenberg.<engine>.request.activegaugeRequests running now.
gotenberg.<engine>.queue.sizegaugeRequests waiting.
gotenberg.<engine>.queue.wait.durationhistogramTime spent in the queue, in seconds.
gotenberg.<engine>.conversion.durationhistogramTime spent converting, in seconds.
gotenberg.<engine>.process.restartscounterEngine restarts.
gotenberg.<engine>.pdf.output.sizehistogramSize of the PDFs it made, in bytes.

A failed request carries an error.type on the requests and durations, such as timeout or invalid_input, and _OTHER for an error Gotenberg doesn't classify. A success carries none, so the failures are the requests with an error.type.

Chromium adds gotenberg.chromium.image.output.size, gotenberg.chromium.network.requests and gotenberg.chromium.network.response.size, and LibreOffice gotenberg.libreoffice.conversion.retries. The HTTP server reports the standard http.server.request.duration, http.server.request.body.size and http.server.response.body.size.

Next​

Run in production.