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.
--log-std-formattakesauto, the default,jsonortext.autowrites text to a terminal, and JSON otherwise.--log-leveltakeserror,warn,info, the default, ordebug.--chromium-debug-protocoladds, atdebug, every message between Gotenberg and Chromium. They carry URLs, cookies and header values whole, credentials included: turn it on only to troubleshoot.--log-std-enable-gcp-fieldsuses the field names Google Cloud Logging reads, and--log-fields-prefixprefixes every field.
Export to OpenTelemetry
The image turns the exporters off. Turn them on with the standard OpenTelemetry variables:
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:
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:
| Metric | Type | What |
|---|---|---|
gotenberg.<engine>.requests | counter | Requests the engine handled. |
gotenberg.<engine>.request.active | gauge | Requests running now. |
gotenberg.<engine>.queue.size | gauge | Requests waiting. |
gotenberg.<engine>.queue.wait.duration | histogram | Time spent in the queue, in seconds. |
gotenberg.<engine>.conversion.duration | histogram | Time spent converting, in seconds. |
gotenberg.<engine>.process.restarts | counter | Engine restarts. |
gotenberg.<engine>.pdf.output.size | histogram | Size 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.