From 137efedba7b4cb3841b06a980273a202d6f7d29b Mon Sep 17 00:00:00 2001 From: Sheddy Date: Tue, 1 Jul 2025 07:54:04 +0100 Subject: [PATCH] Update Logs and Accesslogs Reference Documentation with OTLP Options --- .../observability/logs-and-accesslogs.md | 161 +++++++++++++++++- 1 file changed, 154 insertions(+), 7 deletions(-) diff --git a/docs/content/reference/install-configuration/observability/logs-and-accesslogs.md b/docs/content/reference/install-configuration/observability/logs-and-accesslogs.md index d610fae4d..96dac1ee6 100644 --- a/docs/content/reference/install-configuration/observability/logs-and-accesslogs.md +++ b/docs/content/reference/install-configuration/observability/logs-and-accesslogs.md @@ -44,8 +44,82 @@ The section below describe how to configure Traefik logs using the static config | `log.maxBackups` | Maximum number of old log files to retain.
The default is to retain all old log files. | 0 | No | | `log.compress` | Compress log files in gzip after rotation. | false | No | +### OpenTelemetry + +Traefik supports OpenTelemetry for logging. To enable OpenTelemetry, you need to set the following in the static configuration: + +```yaml tab="File (YAML)" +experimental: + otlpLogs: true +``` + +```toml tab="File (TOML)" +[experimental] + otlpLogs = true +``` + +```sh tab="CLI" +--experimental.otlpLogs=true +``` + +!!! warning + This is an experimental feature. + +#### Configuration Example + +```yaml tab="File (YAML)" +experimental: + otlpLogs: true + +log: + otlp: + http: + endpoint: https://collector:4318/v1/logs + headers: + Authorization: Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL +``` + +```toml tab="File (TOML)" +[experimental] + otlpLogs = true + +[log.otlp] + http.endpoint = "https://collector:4318/v1/logs" + http.headers.Authorization = "Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL" +``` + +```sh tab="CLI" +--experimental.otlpLogs=true +--log.otlp.http.endpoint=https://collector:4318/v1/logs +--log.otlp.http.headers.Authorization=Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL +``` + +#### Configuration Options + +| Field | Description | Default | Required | +|:-----------|:-----------------------------------------------------------------------------|:--------|:---------| +| `log.otlp.http` | This instructs the exporter to send logs to the OpenTelemetry Collector using HTTP.| | No | +| `log.otlp.http.endpoint` | The endpoint of the OpenTelemetry Collector. (format=`://:`) | `https://localhost:4318/v1/logs` | No | +| `log.otlp.http.headers` | Additional headers sent with logs by the exporter to the OpenTelemetry Collector. | [ ] | No | +| `log.otlp.http.tls` | Defines the Client TLS configuration used by the exporter to send logs to the OpenTelemetry Collector. | | No | +| `log.otlp.http.tls.ca` | The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle. | | No | +| `log.otlp.http.tls.cert` | The path to the certificate to use for the OpenTelemetry Collector. | | No | +| `log.otlp.http.tls.key` | The path to the key to use for the OpenTelemetry Collector. | | No | +| `log.otlp.http.tls.insecureSkipVerify` | Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate. | false | No | +| `log.otlp.grpc` | This instructs the exporter to send logs to the OpenTelemetry Collector using gRPC.| | No | +| `log.otlp.grpc.endpoint` | The endpoint of the OpenTelemetry Collector. (format=`:`) | `localhost:4317` | No | +| `log.otlp.grpc.headers` | Additional headers sent with logs by the exporter to the OpenTelemetry Collector. | [ ] | No | +| `log.otlp.grpc.insecure` | Instructs the exporter to send logs to the OpenTelemetry Collector using an insecure protocol. | false | No | +| `log.otlp.grpc.tls` | Defines the Client TLS configuration used by the exporter to send logs to the OpenTelemetry Collector. | | No | +| `log.otlp.grpc.tls.ca` | The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle. | | No | +| `log.otlp.grpc.tls.cert` | The path to the certificate to use for the OpenTelemetry Collector. | | No | +| `log.otlp.grpc.tls.key` | The path to the key to use for the OpenTelemetry Collector. | | No | +| `log.otlp.grpc.tls.insecureSkipVerify` | Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate. | false | No | + ## AccessLogs +Access logs concern everything that happens to the requests handled by Traefik. + ### Configuration Example ```yaml tab="File (YAML)" @@ -111,6 +185,7 @@ accessLog: --accesslog.fields.headers.names.Authorization=drop ``` + ### Configuration Options The section below describes how to configure Traefik access logs using the static configuration. @@ -121,15 +196,87 @@ The section below describes how to configure Traefik access logs using the stati | `accesslog.format` | By default, logs are written using the Common Log Format (CLF).
To write logs in JSON, use `json` in the `format` option.
If the given format is unsupported, the default (CLF) is used instead.
More information about CLF fields [here](#clf-format-fields). | "common" | No | | `accesslog.bufferingSize` | To write the logs in an asynchronous fashion, specify a `bufferingSize` option.
This option represents the number of log lines Traefik will keep in memory before writing them to the selected output.
In some cases, this option can greatly help performances.| 0 | No | | `accesslog.addInternals` | Enables access logs for internal resources (e.g.: `ping@internal`). | false | No | -| `accesslog.filters.statusCodes` | Limit the access logs to requests with a status codes in the specified range. | false | No | +| `accesslog.filters.statusCodes` | Limit the access logs to requests with a status codes in the specified range. | [ ] | No | | `accesslog.filters.retryAttempts` | Keep the access logs when at least one retry has happened. | false | No | | `accesslog.filters.minDuration` | Keep access logs when requests take longer than the specified duration (provided in seconds or as a valid duration format, see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration)). | 0 | No | | `accesslog.fields.defaultMode` | Mode to apply by default to the access logs fields (`keep`, `redact` or `drop`). | keep | No | -| `accesslog.fields.names` | Set the fields list to display in the access logs (format `name:mode`).
Available fields list [here](#available-fields). | - | No | +| `accesslog.fields.names` | Set the fields list to display in the access logs (format `name:mode`).
Available fields list [here](#available-fields). | [ ] | No | | `accesslog.headers.defaultMode` | Mode to apply by default to the access logs headers (`keep`, `redact` or `drop`). | drop | No | -| `accesslog.headers.names` | Set the headers list to display in the access logs (format `name:mode`). | - | No | +| `accesslog.headers.names` | Set the headers list to display in the access logs (format `name:mode`). | [ ] | No | -#### CLF format fields +### OpenTelemetry + +Traefik supports OpenTelemetry for access logs. To enable OpenTelemetry, you need to set the following in the static configuration: + +```yaml tab="File (YAML)" +experimental: + otlpLogs: true +``` + +```toml tab="File (TOML)" +[experimental] + otlpLogs = true +``` + +```sh tab="CLI" +--experimental.otlpLogs=true +``` + +!!! warning + This is an experimental feature. + +#### Configuration Example + +```yaml tab="File (YAML)" +experimental: + otlpLogs: true + +accesslog: + otlp: + http: + endpoint: https://collector:4318/v1/logs + headers: + Authorization: Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL +``` + +```toml tab="File (TOML)" +[experimental] + otlpLogs = true + +[accesslog.otlp] + http.endpoint = "https://collector:4318/v1/logs" + http.headers.Authorization = "Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL" +``` + +```yaml tab="CLI" +--experimental.otlpLogs=true +--accesslog.otlp.http.endpoint=https://collector:4318/v1/logs +--accesslog.otlp.http.headers.Authorization=Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL +``` + +#### Configuration Options + +| Field | Description | Default | Required | +|:-----------|:--------------------------|:--------|:---------| +| `accesslog.otlp.http` | This instructs the exporter to send access logs to the OpenTelemetry Collector using HTTP.| | No | +| `accesslog.otlp.http.endpoint` | The endpoint of the OpenTelemetry Collector. (format=`://:`) | `https://localhost:4318/v1/logs` | No | +| `accesslog.otlp.http.headers` | Additional headers sent with access logs by the exporter to the OpenTelemetry Collector. | [ ] | No | +| `accesslog.otlp.http.tls` | Defines the Client TLS configuration used by the exporter to send access logs to the OpenTelemetry Collector. | | No | +| `accesslog.otlp.http.tls.ca` | The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle. | | No | +| `accesslog.otlp.http.tls.cert` | The path to the certificate to use for the OpenTelemetry Collector. | | No | +| `accesslog.otlp.http.tls.key` | The path to the key to use for the OpenTelemetry Collector. | | No | +| `accesslog.otlp.http.tls.insecureSkipVerify` | Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate. | false | No | +| `accesslog.otlp.grpc` | This instructs the exporter to send access logs to the OpenTelemetry Collector using gRPC.| | No | +| `accesslog.otlp.grpc.endpoint` | The endpoint of the OpenTelemetry Collector. (format=`:`) | `localhost:4317` | No | +| `accesslog.otlp.grpc.headers` | Additional headers sent with access logs by the exporter to the OpenTelemetry Collector. | [ ] | No | +| `accesslog.otlp.grpc.insecure` | Instructs the exporter to send access logs to the OpenTelemetry Collector using an insecure protocol. | false | No | +| `accesslog.otlp.grpc.tls` | Defines the Client TLS configuration used by the exporter to send access logs to the OpenTelemetry Collector. | | No | +| `accesslog.otlp.grpc.tls.ca` | The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle. | | No | +| `accesslog.otlp.grpc.tls.cert` | The path to the certificate to use for the OpenTelemetry Collector. | | No | +| `accesslog.otlp.grpc.tls.key` | The path to the key to use for the OpenTelemetry Collector. | | No | +| `accesslog.otlp.grpc.tls.insecureSkipVerify` | Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate. | false | No | + +### CLF format fields Below the fields displayed with the CLF format: @@ -140,7 +287,7 @@ Below the fields displayed with the CLF format: "" "" ms ``` -#### Available Fields +### Available Fields | Field | Description | |-------------------------|------------------| @@ -179,7 +326,7 @@ Below the fields displayed with the CLF format: | `TLSCipher` | The TLS cipher used by the connection (e.g. `TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA`) (if connection is TLS). | | `TLSClientSubject` | The string representation of the TLS client certificate's Subject (e.g. `CN=username,O=organization`). | -#### Log Rotation +### Log Rotation Traefik close and reopen its log files, assuming they're configured, on receipt of a USR1 signal. This allows the logs to be rotated and processed by an external program, such as `logrotate`. @@ -187,7 +334,7 @@ This allows the logs to be rotated and processed by an external program, such as !!! warning This does not work on Windows due to the lack of USR signals. -#### Time Zones +### Time Zones Traefik will timestamp each log line in UTC time by default.