From d953ee69b4c948ddb7ea0effa121628c003b56d2 Mon Sep 17 00:00:00 2001 From: Kevin Pollet Date: Thu, 12 Dec 2024 12:22:05 +0100 Subject: [PATCH] Add exprimental flag for OTLP logs integration --- cmd/traefik/logger.go | 9 +++++++++ docs/content/observability/access-logs.md | 17 +++++++++++++++++ docs/content/observability/logs.md | 17 +++++++++++++++++ .../reference/static-configuration/cli-ref.md | 5 ++++- .../reference/static-configuration/env-ref.md | 5 ++++- .../reference/static-configuration/file.toml | 1 + .../reference/static-configuration/file.yaml | 1 + pkg/config/static/experimental.go | 4 ++-- pkg/config/static/static_config.go | 8 ++++++++ 9 files changed, 63 insertions(+), 4 deletions(-) diff --git a/cmd/traefik/logger.go b/cmd/traefik/logger.go index 58e664d79..a8b609e4b 100644 --- a/cmd/traefik/logger.go +++ b/cmd/traefik/logger.go @@ -1,6 +1,7 @@ package main import ( + "errors" "fmt" "io" stdlog "log" @@ -22,6 +23,14 @@ func init() { } func setupLogger(staticConfiguration *static.Configuration) error { + // Validate that the experimental flag is set up at this point, + // rather than validating the static configuration before the setupLogger call. + // This ensures that validation messages are not logged using an un-configured logger. + if staticConfiguration.Log != nil && staticConfiguration.Log.OTLP != nil && + (staticConfiguration.Experimental == nil || !staticConfiguration.Experimental.OTLPLogs) { + return errors.New("the experimental OTLPLogs feature must be enabled to use OTLP logging") + } + // configure log format w := getLogWriter(staticConfiguration) diff --git a/docs/content/observability/access-logs.md b/docs/content/observability/access-logs.md index 6f659a9c1..c26d59e61 100644 --- a/docs/content/observability/access-logs.md +++ b/docs/content/observability/access-logs.md @@ -308,6 +308,23 @@ services: ## OpenTelemetry +!!! warning "Experimental Feature" + + The OpenTelemetry access logs feature is currently experimental and must be explicitly enabled in the experimental section prior to use. + + ```yaml tab="File (YAML)" + experimental: + otlpLogs: true + ``` + + ```toml tab="File (TOML)" + [experimental.otlpLogs] + ``` + + ```bash tab="CLI" + --experimental.otlpLogs=true + ``` + To enable the OpenTelemetry Logger for access logs: ```yaml tab="File (YAML)" diff --git a/docs/content/observability/logs.md b/docs/content/observability/logs.md index 8b774c406..51be940b8 100644 --- a/docs/content/observability/logs.md +++ b/docs/content/observability/logs.md @@ -183,6 +183,23 @@ log: ## OpenTelemetry +!!! warning "Experimental Feature" + + The OpenTelemetry logs feature is currently experimental and must be explicitly enabled in the experimental section prior to use. + + ```yaml tab="File (YAML)" + experimental: + otlpLogs: true + ``` + + ```toml tab="File (TOML)" + [experimental.otlpLogs] + ``` + + ```bash tab="CLI" + --experimental.otlpLogs=true + ``` + To enable the OpenTelemetry Logger for logs: ```yaml tab="File (YAML)" diff --git a/docs/content/reference/static-configuration/cli-ref.md b/docs/content/reference/static-configuration/cli-ref.md index 7feb19120..e963cfb68 100644 --- a/docs/content/reference/static-configuration/cli-ref.md +++ b/docs/content/reference/static-configuration/cli-ref.md @@ -313,7 +313,7 @@ Timeout defines how long to wait on an idle session before releasing the related Defines whether all plugins must be loaded successfully for Traefik to start. (Default: ```false```) `--experimental.fastproxy`: -Enable the FastProxy implementation. (Default: ```false```) +Enables the FastProxy implementation. (Default: ```false```) `--experimental.fastproxy.debug`: Enable debug mode for the FastProxy implementation. (Default: ```false```) @@ -336,6 +336,9 @@ Environment variables to forward to the wasm guest. `--experimental.localplugins..settings.mounts`: Directory to mount to the wasm guest. +`--experimental.otlplogs`: +Enables the OpenTelemetry logs integration. (Default: ```false```) + `--experimental.plugins..modulename`: plugin's module name. diff --git a/docs/content/reference/static-configuration/env-ref.md b/docs/content/reference/static-configuration/env-ref.md index 5a82b515e..b89a048e3 100644 --- a/docs/content/reference/static-configuration/env-ref.md +++ b/docs/content/reference/static-configuration/env-ref.md @@ -313,7 +313,7 @@ Timeout defines how long to wait on an idle session before releasing the related Defines whether all plugins must be loaded successfully for Traefik to start. (Default: ```false```) `TRAEFIK_EXPERIMENTAL_FASTPROXY`: -Enable the FastProxy implementation. (Default: ```false```) +Enables the FastProxy implementation. (Default: ```false```) `TRAEFIK_EXPERIMENTAL_FASTPROXY_DEBUG`: Enable debug mode for the FastProxy implementation. (Default: ```false```) @@ -336,6 +336,9 @@ Environment variables to forward to the wasm guest. `TRAEFIK_EXPERIMENTAL_LOCALPLUGINS__SETTINGS_MOUNTS`: Directory to mount to the wasm guest. +`TRAEFIK_EXPERIMENTAL_OTLPLOGS`: +Enables the OpenTelemetry logs integration. (Default: ```false```) + `TRAEFIK_EXPERIMENTAL_PLUGINS__MODULENAME`: plugin's module name. diff --git a/docs/content/reference/static-configuration/file.toml b/docs/content/reference/static-configuration/file.toml index 25653d0ce..c379e0261 100644 --- a/docs/content/reference/static-configuration/file.toml +++ b/docs/content/reference/static-configuration/file.toml @@ -559,6 +559,7 @@ [experimental] abortOnPluginFailure = true + otlplogs = true kubernetesGateway = true [experimental.plugins] [experimental.plugins.Descriptor0] diff --git a/docs/content/reference/static-configuration/file.yaml b/docs/content/reference/static-configuration/file.yaml index d40decc22..a0a9bbf68 100644 --- a/docs/content/reference/static-configuration/file.yaml +++ b/docs/content/reference/static-configuration/file.yaml @@ -649,6 +649,7 @@ experimental: abortOnPluginFailure: true fastProxy: debug: true + otlplogs: true kubernetesGateway: true core: defaultRuleSyntax: foobar diff --git a/pkg/config/static/experimental.go b/pkg/config/static/experimental.go index 099b97f6d..f88564637 100644 --- a/pkg/config/static/experimental.go +++ b/pkg/config/static/experimental.go @@ -7,8 +7,8 @@ type Experimental struct { Plugins map[string]plugins.Descriptor `description:"Plugins configuration." json:"plugins,omitempty" toml:"plugins,omitempty" yaml:"plugins,omitempty" export:"true"` LocalPlugins map[string]plugins.LocalDescriptor `description:"Local plugins configuration." json:"localPlugins,omitempty" toml:"localPlugins,omitempty" yaml:"localPlugins,omitempty" export:"true"` AbortOnPluginFailure bool `description:"Defines whether all plugins must be loaded successfully for Traefik to start." json:"abortOnPluginFailure,omitempty" toml:"abortOnPluginFailure,omitempty" yaml:"abortOnPluginFailure,omitempty" export:"true"` - - FastProxy *FastProxyConfig `description:"Enable the FastProxy implementation." json:"fastProxy,omitempty" toml:"fastProxy,omitempty" yaml:"fastProxy,omitempty" label:"allowEmpty" file:"allowEmpty" export:"true"` + FastProxy *FastProxyConfig `description:"Enables the FastProxy implementation." json:"fastProxy,omitempty" toml:"fastProxy,omitempty" yaml:"fastProxy,omitempty" label:"allowEmpty" file:"allowEmpty" export:"true"` + OTLPLogs bool `description:"Enables the OpenTelemetry logs integration." json:"otlplogs,omitempty" toml:"otlplogs,omitempty" yaml:"otlplogs,omitempty" export:"true"` // Deprecated: KubernetesGateway provider is not an experimental feature starting with v3.1. Please remove its usage from the static configuration. KubernetesGateway bool `description:"(Deprecated) Allow the Kubernetes gateway api provider usage." json:"kubernetesGateway,omitempty" toml:"kubernetesGateway,omitempty" yaml:"kubernetesGateway,omitempty" export:"true"` diff --git a/pkg/config/static/static_config.go b/pkg/config/static/static_config.go index 4f6dad22a..c254711df 100644 --- a/pkg/config/static/static_config.go +++ b/pkg/config/static/static_config.go @@ -387,12 +387,20 @@ func (c *Configuration) ValidateConfiguration() error { } if c.AccessLog != nil && c.AccessLog.OTLP != nil { + if c.Experimental == nil || !c.Experimental.OTLPLogs { + return errors.New("the experimental OTLPLogs feature must be enabled to use OTLP access logging") + } + if c.AccessLog.OTLP.GRPC != nil && c.AccessLog.OTLP.GRPC.TLS != nil && c.AccessLog.OTLP.GRPC.Insecure { return errors.New("access logs OTLP GRPC: TLS and Insecure options are mutually exclusive") } } if c.Log != nil && c.Log.OTLP != nil { + if c.Experimental == nil || !c.Experimental.OTLPLogs { + return errors.New("the experimental OTLPLogs feature must be enabled to use OTLP logging") + } + if c.Log.OTLP.GRPC != nil && c.Log.OTLP.GRPC.TLS != nil && c.Log.OTLP.GRPC.Insecure { return errors.New("logs OTLP GRPC: TLS and Insecure options are mutually exclusive") }