Skip to content

Commit c1ab0f7

Browse files
guliengulien
committed
docs: update for Gotenberg 8.29.0 with telemetry, new flags, deprecated flags, new features
1 parent f00691d commit c1ab0f7

6 files changed

Lines changed: 465 additions & 58 deletions

File tree

‎docs/configuration.mdx‎

Lines changed: 82 additions & 58 deletions
Large diffs are not rendered by default.

‎docs/convert-with-libreoffice/convert-to-pdf.mdx‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -721,4 +721,119 @@ curl \\
721721
curlOutput={`-o my.pdf`}
722722
/>
723723

724+
## PDF Viewer Preferences
725+
726+
Control how PDF viewers display the document on open. These preferences are embedded during conversion and take effect when a reader (Adobe Acrobat, browser PDF viewer, etc.) opens the file.
727+
728+
<ApiEndpoint
729+
formFields={[
730+
{
731+
name: "initialView",
732+
type: "integer",
733+
defaultValue: "0",
734+
description:
735+
"Initial view when opening the PDF. 0: neither document outline nor thumbnails. 1: document outline visible. 2: thumbnail images visible.",
736+
},
737+
{
738+
name: "initialPage",
739+
type: "integer",
740+
defaultValue: "1",
741+
description: "The page on which the PDF opens.",
742+
},
743+
{
744+
name: "magnification",
745+
type: "integer",
746+
defaultValue: "0",
747+
description:
748+
"Initial magnification level. 0: default. 1: fit page. 2: fit width. 3: fit visible. 4: use zoom value.",
749+
},
750+
{
751+
name: "zoom",
752+
type: "integer",
753+
defaultValue: "100",
754+
description: "Initial zoom percentage when magnification is set to 4.",
755+
},
756+
{
757+
name: "pageLayout",
758+
type: "integer",
759+
defaultValue: "0",
760+
description:
761+
"Page layout. 0: default. 1: single page. 2: one column. 3: two columns.",
762+
},
763+
{
764+
name: "firstPageOnLeft",
765+
type: "boolean",
766+
defaultValue: "false",
767+
description:
768+
"Place the first page on the left when using two-column page layout.",
769+
},
770+
{
771+
name: "resizeWindowToInitialPage",
772+
type: "boolean",
773+
defaultValue: "false",
774+
description: "Resize the viewer window to the size of the first page.",
775+
},
776+
{
777+
name: "centerWindow",
778+
type: "boolean",
779+
defaultValue: "false",
780+
description: "Center the viewer window on the screen.",
781+
},
782+
{
783+
name: "openInFullScreenMode",
784+
type: "boolean",
785+
defaultValue: "false",
786+
description: "Open the PDF in full-screen mode.",
787+
},
788+
{
789+
name: "displayPDFDocumentTitle",
790+
type: "boolean",
791+
defaultValue: "true",
792+
description:
793+
"Display the document title in the viewer title bar instead of the filename.",
794+
},
795+
{
796+
name: "hideViewerMenubar",
797+
type: "boolean",
798+
defaultValue: "false",
799+
description: "Hide the viewer menu bar.",
800+
},
801+
{
802+
name: "hideViewerToolbar",
803+
type: "boolean",
804+
defaultValue: "false",
805+
description: "Hide the viewer toolbar.",
806+
},
807+
{
808+
name: "hideViewerWindowControls",
809+
type: "boolean",
810+
defaultValue: "false",
811+
description: "Hide the viewer window controls.",
812+
},
813+
{
814+
name: "useTransitionEffects",
815+
type: "boolean",
816+
defaultValue: "true",
817+
description:
818+
"Use transition effects when advancing slides in Impress presentations.",
819+
},
820+
{
821+
name: "openBookmarkLevels",
822+
type: "integer",
823+
defaultValue: "-1",
824+
description:
825+
"Number of bookmark levels to show when opening the PDF. -1 shows all levels.",
826+
},
827+
]}
828+
curl={`
829+
curl \\
830+
--request POST http://localhost:3000/forms/libreoffice/convert \\
831+
--form files=@/path/to/document.docx \\
832+
--form initialView=1 \\
833+
--form magnification=2 \\
834+
--form displayPDFDocumentTitle=true \\
835+
--form hideViewerToolbar=true \\
836+
-o my.pdf`}
837+
/>
838+
724839
<Sponsors />

‎docs/system/prometheus-metrics.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@ import Sponsors from "@site/src/components/documentation/Sponsors";
88

99
Exposes internal metrics in [Prometheus](https://prometheus.io/) format. See the [Prometheus module configuration](/docs/configuration#prometheus) for details.
1010

11+
:::warning
12+
13+
As of Gotenberg _8.29.0_, this endpoint is deprecated. Use [OpenTelemetry](/docs/telemetry) for observability, including for [migrating from Prometheus](/docs/telemetry#migrating-from-prometheus).
14+
15+
:::
16+
1117
<ApiEndpoint
1218
method="GET"
1319
path="/prometheus/metrics"

‎docs/telemetry.mdx‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
---
2+
id: telemetry
3+
title: Telemetry
4+
---
5+
6+
import Sponsors from "@site/src/components/documentation/Sponsors";
7+
8+
Gotenberg integrates [OpenTelemetry](https://opentelemetry.io/) for distributed tracing, metrics export, and structured log shipping. All three signals are configured via standard OTEL environment variables.
9+
10+
## Traces
11+
12+
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](https://www.w3.org/TR/trace-context/) headers.
13+
14+
Configure tracing with standard OTEL environment variables:
15+
16+
| Environment variable | Description | Default |
17+
| ------------------------------------ | ------------------------------------------------------------------------ | ----------- |
18+
| `OTEL_TRACES_EXPORTER` | Trace exporter. Options: `none`, `otlp`, `jaeger`, `zipkin`. | `none` |
19+
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint for all signals (traces, metrics, logs). | None |
20+
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | OTLP endpoint specifically for traces. Overrides the generic endpoint. | None |
21+
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP transport protocol. Options: `grpc`, `http/protobuf`. | `grpc` |
22+
| `OTEL_EXPORTER_OTLP_HEADERS` | Headers to send with OTLP requests (e.g., `Authorization=Bearer token`). | None |
23+
| `OTEL_SERVICE_NAME` | Logical service name attached to all telemetry. | `gotenberg` |
24+
25+
```yaml title="compose.yaml"
26+
services:
27+
gotenberg:
28+
image: gotenberg/gotenberg:8
29+
environment:
30+
OTEL_SERVICE_NAME: "gotenberg"
31+
OTEL_TRACES_EXPORTER: "otlp"
32+
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
33+
34+
otel-collector:
35+
image: otel/opentelemetry-collector-contrib
36+
# Configure your collector pipeline as needed.
37+
```
38+
39+
## Metrics
40+
41+
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.
42+
43+
Configure metrics export with standard OTEL environment variables:
44+
45+
| Environment variable | Description | Default |
46+
| ------------------------------------- | ----------------------------------------------------------------------- | ------- |
47+
| `OTEL_METRICS_EXPORTER` | Metrics exporter. Options: `none`, `otlp`, `prometheus`. | `none` |
48+
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint for all signals (traces, metrics, logs). | None |
49+
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | OTLP endpoint specifically for metrics. Overrides the generic endpoint. | None |
50+
51+
### Migrating from Prometheus
52+
53+
The [Prometheus metrics endpoint](/docs/system/prometheus-metrics) is deprecated as of Gotenberg _8.29.0_. Replace it with OTEL-based metrics export.
54+
55+
**Option 1: OTLP to a Prometheus-compatible backend**
56+
57+
Send metrics via OTLP to a collector that writes to Prometheus, Mimir, or any compatible backend:
58+
59+
```yaml title="compose.yaml"
60+
services:
61+
gotenberg:
62+
image: gotenberg/gotenberg:8
63+
environment:
64+
OTEL_METRICS_EXPORTER: "otlp"
65+
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
66+
67+
otel-collector:
68+
image: otel/opentelemetry-collector-contrib
69+
volumes:
70+
- ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
71+
```
72+
73+
```yaml title="otel-collector-config.yaml"
74+
receivers:
75+
otlp:
76+
protocols:
77+
grpc:
78+
endpoint: 0.0.0.0:4317
79+
80+
exporters:
81+
prometheusremotewrite:
82+
endpoint: "http://prometheus:9090/api/v1/write"
83+
84+
service:
85+
pipelines:
86+
metrics:
87+
receivers: [otlp]
88+
exporters: [prometheusremotewrite]
89+
```
90+
91+
**Option 2: Built-in Prometheus exporter**
92+
93+
Expose a Prometheus-compatible scrape endpoint directly from Gotenberg via the OTEL SDK. By default, metrics are served at `localhost:9464/metrics`.
94+
95+
```yaml title="compose.yaml"
96+
services:
97+
gotenberg:
98+
image: gotenberg/gotenberg:8
99+
ports:
100+
- "3000:3000"
101+
- "9464:9464"
102+
environment:
103+
OTEL_METRICS_EXPORTER: "prometheus"
104+
# Optional: customize host and port.
105+
# OTEL_EXPORTER_PROMETHEUS_HOST: "0.0.0.0"
106+
# OTEL_EXPORTER_PROMETHEUS_PORT: "9464"
107+
108+
prometheus:
109+
image: prom/prometheus
110+
volumes:
111+
- ./prometheus.yml:/etc/prometheus/prometheus.yml
112+
```
113+
114+
```yaml title="prometheus.yml"
115+
scrape_configs:
116+
- job_name: "gotenberg"
117+
scrape_interval: 10s
118+
static_configs:
119+
- targets: ["gotenberg:9464"]
120+
```
121+
122+
This is separate from the legacy `/prometheus/metrics` route and does not require the Prometheus module flags.
123+
124+
## Logs
125+
126+
Gotenberg uses `slog`-based structured logging. An OTEL log bridge exports logs to configured OTEL backends alongside stdout output.
127+
128+
Configure log export with standard OTEL environment variables:
129+
130+
| Environment variable | Description | Default |
131+
| ---------------------------------- | -------------------------------------------------------------------- | ------- |
132+
| `OTEL_LOGS_EXPORTER` | Logs exporter. Options: `none`, `otlp`. | `none` |
133+
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint for all signals (traces, metrics, logs). | None |
134+
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP endpoint specifically for logs. Overrides the generic endpoint. | None |
135+
136+
### Stdout Configuration
137+
138+
The following flags control stdout log output. See the [Logging configuration](/docs/configuration#logging) for the full list.
139+
140+
| Flag | Environment variable | Description | Default |
141+
| ----------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- | ------- |
142+
| <span class="badge badge--secondary">--log-std-format</span> | <span class="badge badge--secondary">LOG_STD_FORMAT</span> | Specify the format of logging. Options: auto, json, text. | auto |
143+
| <span class="badge badge--secondary">--log-std-enable-gcp-fields</span> | <span class="badge badge--secondary">LOG_STD_ENABLE_GCP_FIELDS</span> | Use GCP-compatible field names (time, message, severity). | false |
144+
145+
:::warning
146+
147+
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`.
148+
149+
:::
150+
151+
## Telemetry Control
152+
153+
Suppress telemetry (traces, metrics, logs) on high-frequency system routes to reduce noise. All default to `true` (disabled).
154+
155+
| Flag | Environment variable | Description | Default |
156+
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------- | --------------- |
157+
| <span class="badge badge--secondary">--api-correlation-id-header</span> | <span class="badge badge--secondary">API_CORRELATION_ID_HEADER</span> | Header name for identifying requests. | Gotenberg-Trace |
158+
| <span class="badge badge--secondary">--api-disable-root-route-telemetry</span> | <span class="badge badge--secondary">API_DISABLE_ROOT_ROUTE_TELEMETRY</span> | Disable telemetry for the root route. | true |
159+
| <span class="badge badge--secondary">--api-disable-debug-route-telemetry</span> | <span class="badge badge--secondary">API_DISABLE_DEBUG_ROUTE_TELEMETRY</span> | Disable telemetry for the debug route. | true |
160+
| <span class="badge badge--secondary">--api-disable-version-route-telemetry</span> | <span class="badge badge--secondary">API_DISABLE_VERSION_ROUTE_TELEMETRY</span> | Disable telemetry for the version route. | true |
161+
| <span class="badge badge--secondary">--api-disable-health-check-route-telemetry</span> | <span class="badge badge--secondary">API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY</span> | Disable telemetry for the health check route. | true |
162+
| <span class="badge badge--secondary">--prometheus-disable-route-telemetry</span> | <span class="badge badge--secondary">PROMETHEUS_DISABLE_ROUTE_TELEMETRY</span> | Disable telemetry for the Prometheus metrics route. | true |
163+
164+
:::warning
165+
166+
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`.
167+
168+
:::
169+
170+
## Example
171+
172+
A complete Docker Compose setup with Gotenberg exporting traces, metrics, and logs to an OTEL Collector:
173+
174+
```yaml title="compose.yaml"
175+
services:
176+
gotenberg:
177+
image: gotenberg/gotenberg:8
178+
ports:
179+
- "3000:3000"
180+
environment:
181+
OTEL_SERVICE_NAME: "gotenberg"
182+
OTEL_TRACES_EXPORTER: "otlp"
183+
OTEL_METRICS_EXPORTER: "otlp"
184+
OTEL_LOGS_EXPORTER: "otlp"
185+
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
186+
187+
otel-collector:
188+
image: otel/opentelemetry-collector-contrib
189+
ports:
190+
- "4317:4317"
191+
volumes:
192+
- ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
193+
```
194+
195+
```yaml title="otel-collector-config.yaml"
196+
receivers:
197+
otlp:
198+
protocols:
199+
grpc:
200+
endpoint: 0.0.0.0:4317
201+
202+
exporters:
203+
# Replace with your preferred backend (Jaeger, Grafana Cloud, Datadog, etc.).
204+
debug:
205+
verbosity: detailed
206+
207+
service:
208+
pipelines:
209+
traces:
210+
receivers: [otlp]
211+
exporters: [debug]
212+
metrics:
213+
receivers: [otlp]
214+
exporters: [debug]
215+
logs:
216+
receivers: [otlp]
217+
exporters: [debug]
218+
```
219+
220+
<Sponsors />

0 commit comments

Comments
 (0)