From 886984919023978b56d03a2b0b11feedc535857e Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 17 Apr 2025 11:42:21 +0200 Subject: [PATCH 01/11] docs: Add initial telemetry docs --- modules/concepts/nav.adoc | 7 ++-- .../pages/observability/telemetry.adoc | 32 +++++++++++++++++++ 2 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 modules/concepts/pages/observability/telemetry.adoc diff --git a/modules/concepts/nav.adoc b/modules/concepts/nav.adoc index 311f5cd62..458e753a3 100644 --- a/modules/concepts/nav.adoc +++ b/modules/concepts/nav.adoc @@ -22,7 +22,8 @@ *** xref:operations/graceful_shutdown.adoc[] *** xref:operations/temporary_credentials_lifetime.adoc[] ** Observability -*** xref:labels.adoc[] -*** xref:logging.adoc[] -*** xref:containerdebug.adoc[] +*** xref:labels.adoc[Labels] +*** xref:logging.adoc[Logging] +*** xref:containerdebug.adoc[Container environment] +*** xref:observability/telemetry.adoc[Telemetry] ** xref:container-images.adoc[] diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc new file mode 100644 index 000000000..f1d9efaae --- /dev/null +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -0,0 +1,32 @@ += Telemetry signals in operators + +Since SDP 25.7.0, all Stackable operators emit multiple signals for telemetry data. +Currently supported signals are: + +* Console logs in plain and JSON format +* (Rolling) file logs in JSON format +* OpenTelemetry logs exported via OTLP +* OpenTelemetry traces exported via OTLP + +Every signal can be toggled and customized using Helm values. +All fields are grouped under the top-level `telemetry` section. +The following sections describe the available fields their default and supported values. + +== Console logs + +This signal prints log messages at the selected level and in the selected format to STDOUT. +These logs are useful for quick debugging. +For a more complete debugging experience, we recommend the OpenTelemetry signals. + +[source,yaml] +---- +telemetry: + consoleLog: + enabled: true # true, false + level: null # error, warning, info, debug, trace + format: null # plain, json +---- + +== File logs + +== OpenTelemetry logs and traces From 2bfb490d070f604e7322974bb55c474d0a15a0d3 Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 24 Apr 2025 13:36:23 +0200 Subject: [PATCH 02/11] docs: Use code callouts --- modules/concepts/pages/observability/telemetry.adoc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index f1d9efaae..75b294fdf 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -22,11 +22,15 @@ For a more complete debugging experience, we recommend the OpenTelemetry signals ---- telemetry: consoleLog: - enabled: true # true, false - level: null # error, warning, info, debug, trace - format: null # plain, json + enabled: true # <1> + level: null # <2> + format: null # <3> ---- +<1> Boolean: `true, false` +<2> Enum: `error, warning, info, debug, trace` +<3> Enum: `plain, json` + == File logs == OpenTelemetry logs and traces From 4a15d1abf829fda3831ce738277251d63953433c Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 24 Apr 2025 13:36:55 +0200 Subject: [PATCH 03/11] docs: Add section for file logs --- .../pages/observability/telemetry.adoc | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index 75b294fdf..4a356b114 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -33,4 +33,22 @@ telemetry: == File logs +This signal writes log messages at the selected level in JSON to (rolling) log file(s). +These logs can be picked up by log aggregation systems, like Vector. + +[source,yaml] +---- +telemetry: + fileLog: + enabled: false # <1> + level: null # <2> + rotationPeriod: hourly # <3> + maxFiles: 6 # <4> +---- + +<1> Boolean: `true, false` +<2> Enum: `error, warning, info, debug, trace` +<3> Enum: `never, daily, hourly, minutely` +<4> Unsigned Integer + == OpenTelemetry logs and traces From 75cf3d7e59b97e0148d2497139edef3e8b7b48b7 Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 24 Apr 2025 13:37:12 +0200 Subject: [PATCH 04/11] docs: Add OpenTelemetry logs and traces section --- .../pages/observability/telemetry.adoc | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index 4a356b114..62ed14182 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -52,3 +52,23 @@ telemetry: <4> Unsigned Integer == OpenTelemetry logs and traces + +These two signal export OpenTelemetry logs and traces to OTLP enabled collectors. +These signals can be visualized using tools, like Grafana, Loki, and Jaeger. + +[source,yaml] +---- +telemetry: + otelLogExporter: + enabled: false # <1> + level: null # <2> + endpoint: null # <3> + otelTraceExporter: + enabled: false # <1> + level: null # <2> + endpoint: null # <3> +---- + +<1> Boolean: `true, false` +<2> Enum: `error, warning, info, debug, trace` +<3> String: E.g. `my-collector:4317` From f805aceed4e0db104b01dfc7d2d99685356b6f92 Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 24 Apr 2025 14:35:04 +0200 Subject: [PATCH 05/11] docs: Add admonition about default and supported values --- modules/concepts/pages/observability/telemetry.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index 62ed14182..430e32a53 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -10,7 +10,8 @@ Currently supported signals are: Every signal can be toggled and customized using Helm values. All fields are grouped under the top-level `telemetry` section. -The following sections describe the available fields their default and supported values. + +NOTE: The following sections describe the available fields their default and supported values. == Console logs From e230821cb287dae533b8ae00048da9b4225a227b Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 24 Apr 2025 14:35:34 +0200 Subject: [PATCH 06/11] docs: Add operator default values --- modules/concepts/pages/observability/telemetry.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index 430e32a53..fea926ffe 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -29,8 +29,8 @@ telemetry: ---- <1> Boolean: `true, false` -<2> Enum: `error, warning, info, debug, trace` -<3> Enum: `plain, json` +<2> Enum: `error, warning, info, debug, trace` - operator defaults to `info` +<3> Enum: `plain, json` - operator defaults to `plain` == File logs @@ -48,7 +48,7 @@ telemetry: ---- <1> Boolean: `true, false` -<2> Enum: `error, warning, info, debug, trace` +<2> Enum: `error, warning, info, debug, trace` - operator defaults to `info` <3> Enum: `never, daily, hourly, minutely` <4> Unsigned Integer @@ -71,5 +71,5 @@ telemetry: ---- <1> Boolean: `true, false` -<2> Enum: `error, warning, info, debug, trace` +<2> Enum: `error, warning, info, debug, trace` - operator defaults to `info` <3> String: E.g. `my-collector:4317` From 732e0625ea5d5bea1c5192d460353c3aa6b90670 Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 24 Apr 2025 14:42:33 +0200 Subject: [PATCH 07/11] docs: Adjust available signals section --- modules/concepts/pages/observability/telemetry.adoc | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index fea926ffe..f84baa0bd 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -1,12 +1,10 @@ = Telemetry signals in operators -Since SDP 25.7.0, all Stackable operators emit multiple signals for telemetry data. -Currently supported signals are: +Since SDP 25.7.0, all Stackable operators emit telemetry data in the following ways: -* Console logs in plain and JSON format -* (Rolling) file logs in JSON format -* OpenTelemetry logs exported via OTLP -* OpenTelemetry traces exported via OTLP +* logs (via console, file, and OTLP export) +* metrics (not yet available, will most likely be an OTLP export) +* traces (via OTLP export) Every signal can be toggled and customized using Helm values. All fields are grouped under the top-level `telemetry` section. From e3fc6e824d4160984bbf312e0a5d3d4bfdf9489f Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 24 Apr 2025 16:03:31 +0200 Subject: [PATCH 08/11] docs: Remove metrics signal --- modules/concepts/pages/observability/telemetry.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index f84baa0bd..e500a5ba5 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -3,7 +3,6 @@ Since SDP 25.7.0, all Stackable operators emit telemetry data in the following ways: * logs (via console, file, and OTLP export) -* metrics (not yet available, will most likely be an OTLP export) * traces (via OTLP export) Every signal can be toggled and customized using Helm values. From 4da981717a27f6fb1d4b133369c0242767a8fc44 Mon Sep 17 00:00:00 2001 From: Techassi Date: Fri, 25 Apr 2025 10:04:38 +0200 Subject: [PATCH 09/11] chore: Apply suggestion Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> --- modules/concepts/pages/observability/telemetry.adoc | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index e500a5ba5..3da7f68f5 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -2,10 +2,12 @@ Since SDP 25.7.0, all Stackable operators emit telemetry data in the following ways: -* logs (via console, file, and OTLP export) -* traces (via OTLP export) +* Console logs in plain and JSON format +* File logs in JSON format (with the option of Rolling files) +* OpenTelemetry logs exported via OTLP +* OpenTelemetry traces exported via OTLP -Every signal can be toggled and customized using Helm values. +Every subscriber can be toggled and customized using Helm values. All fields are grouped under the top-level `telemetry` section. NOTE: The following sections describe the available fields their default and supported values. From 62bd563547e1ae37a30cb177cab9d26d1ad36f0b Mon Sep 17 00:00:00 2001 From: Techassi Date: Fri, 25 Apr 2025 10:11:06 +0200 Subject: [PATCH 10/11] docs: Adjust note about operator defaults --- .../pages/observability/telemetry.adoc | 22 ++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index 3da7f68f5..8d3de18c5 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -10,7 +10,19 @@ Since SDP 25.7.0, all Stackable operators emit telemetry data in the following w Every subscriber can be toggled and customized using Helm values. All fields are grouped under the top-level `telemetry` section. -NOTE: The following sections describe the available fields their default and supported values. +[NOTE] +==== +The following sections describe the available fields as well as their default and supported values. +If the Helm values explained below are not overridden, the following operator defaults apply: + +* Levels for all signals are set to `INFO`. +* Console logs are enabled +* File logs are disabled +* File logs rotation period is set to `Never` +* File logs max files is unset +* OpenTelemetry logs and traces are disabled +* OTLP endpoints are set to `http://localhost:4317` +==== == Console logs @@ -28,8 +40,8 @@ telemetry: ---- <1> Boolean: `true, false` -<2> Enum: `error, warning, info, debug, trace` - operator defaults to `info` -<3> Enum: `plain, json` - operator defaults to `plain` +<2> Enum: `error, warning, info, debug, trace` +<3> Enum: `plain, json` == File logs @@ -47,7 +59,7 @@ telemetry: ---- <1> Boolean: `true, false` -<2> Enum: `error, warning, info, debug, trace` - operator defaults to `info` +<2> Enum: `error, warning, info, debug, trace` <3> Enum: `never, daily, hourly, minutely` <4> Unsigned Integer @@ -70,5 +82,5 @@ telemetry: ---- <1> Boolean: `true, false` -<2> Enum: `error, warning, info, debug, trace` - operator defaults to `info` +<2> Enum: `error, warning, info, debug, trace` <3> String: E.g. `my-collector:4317` From 7103abc9b050d73b0f8d1b9a380402df950868aa Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 28 Apr 2025 16:19:02 +0200 Subject: [PATCH 11/11] chore: Apply suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Natalie Klestrup Röijezon --- modules/concepts/pages/observability/telemetry.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc index 8d3de18c5..58ec67fa1 100644 --- a/modules/concepts/pages/observability/telemetry.adoc +++ b/modules/concepts/pages/observability/telemetry.adoc @@ -46,7 +46,7 @@ telemetry: == File logs This signal writes log messages at the selected level in JSON to (rolling) log file(s). -These logs can be picked up by log aggregation systems, like Vector. +These logs can be picked up by a log aggregation system, like Vector. [source,yaml] ----