From 2437007d1300e9b71e858e9ffbed638c01d3aed8 Mon Sep 17 00:00:00 2001 From: Techassi Date: Fri, 4 Apr 2025 14:43:15 +0200 Subject: [PATCH 01/15] feat: Add method to construct pre-configured Tracing instance --- Cargo.lock | 2 + crates/stackable-telemetry/Cargo.toml | 5 + crates/stackable-telemetry/src/tracing/mod.rs | 114 +++++++++++++++++- .../src/tracing/settings/file_log.rs | 4 +- 4 files changed, 122 insertions(+), 3 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ff786d846..93398cbc6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3247,6 +3247,7 @@ name = "stackable-telemetry" version = "0.4.0" dependencies = [ "axum 0.8.3", + "clap", "futures-util", "opentelemetry", "opentelemetry-appender-tracing", @@ -3256,6 +3257,7 @@ dependencies = [ "rstest", "snafu 0.8.5", "stackable-webhook", + "strum", "tokio", "tower 0.5.2", "tracing", diff --git a/crates/stackable-telemetry/Cargo.toml b/crates/stackable-telemetry/Cargo.toml index 1c75fb9f2..dc889a010 100644 --- a/crates/stackable-telemetry/Cargo.toml +++ b/crates/stackable-telemetry/Cargo.toml @@ -6,8 +6,12 @@ license.workspace = true edition.workspace = true repository.workspace = true +[features] +clap = ["dep:clap"] + [dependencies] axum.workspace = true +clap = { workspace = true, optional = true } futures-util.workspace = true opentelemetry = { workspace = true, features = ["logs"] } opentelemetry-appender-tracing.workspace = true @@ -16,6 +20,7 @@ opentelemetry-otlp = { workspace = true, features = ["grpc-tonic", "gzip-tonic", opentelemetry_sdk = { workspace = true, features = ["logs", "rt-tokio", "spec_unstable_logs_enabled"] } pin-project.workspace = true snafu.workspace = true +strum.workspace = true tokio.workspace = true tower.workspace = true tracing.workspace = true diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index ce2e60c5f..8c0fdca81 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -6,6 +6,8 @@ //! //! To get started, see [`Tracing`]. +use std::path::PathBuf; + use opentelemetry::trace::TracerProvider; use opentelemetry_appender_tracing::layer::OpenTelemetryTracingBridge; use opentelemetry_otlp::{LogExporter, SpanExporter}; @@ -14,7 +16,7 @@ use opentelemetry_sdk::{ trace::SdkTracerProvider, }; use snafu::{ResultExt as _, Snafu}; -use tracing::subscriber::SetGlobalDefaultError; +use tracing::{level_filters::LevelFilter, subscriber::SetGlobalDefaultError}; use tracing_appender::rolling::{InitError, RollingFileAppender}; use tracing_subscriber::{EnvFilter, Layer, Registry, filter::Directive, layer::SubscriberExt}; @@ -244,11 +246,58 @@ pub struct Tracing { } impl Tracing { + /// The environment variable used to set the console log level filter. + pub const CONSOLE_LOG_ENV_VAR: &str = "CONSOLE_LOG"; + /// The environment variable used to set the rolling file log level filter. + pub const FILE_LOG_ENV_VAR: &str = "FILE_LOG"; + /// The filename used for the rolling file logs. + pub const FILE_LOG_NAME: &str = "operator.log"; + /// The environment variable used to set the OTLP log level filter. + pub const OTLP_LOG_ENV_VAR: &str = "OTLP_LOG"; + /// The environment variable used to set the OTLP trace level filter. + pub const OTLP_TRACE_ENV_VAR: &str = "OTLP_TRACE"; + /// Creates and returns a [`TracingBuilder`]. pub fn builder() -> TracingBuilder { TracingBuilder::default() } + /// Creates an returns a pre-configured [`Tracing`] instance which can be initialized by + /// calling [`Tracing::init()`]. + /// + /// If `rolling_logs_period` is [`None`], this function will use a default value of + /// [`RollingPeriod::Never`]. + pub fn pre_configured(service_name: &'static str, options: TelemetryOptions) -> Self { + let TelemetryOptions { + no_console_output, + rolling_logs, + rolling_logs_period, + otlp_traces, + otlp_logs, + } = options; + + let rolling_logs_period = rolling_logs_period.unwrap_or_default(); + + Self::builder() + .service_name(service_name) + .with_console_output(( + Self::CONSOLE_LOG_ENV_VAR, + LevelFilter::INFO, + !no_console_output, + )) + .with_file_output(rolling_logs.map(|log_directory| { + Settings::builder() + .with_environment_variable(Self::FILE_LOG_ENV_VAR) + .with_default_level(LevelFilter::INFO) + .file_log_settings_builder(log_directory, Self::FILE_LOG_NAME) + .with_rotation_period(rolling_logs_period) + .build() + })) + .with_otlp_log_exporter((Self::OTLP_LOG_ENV_VAR, LevelFilter::DEBUG, otlp_logs)) + .with_otlp_trace_exporter((Self::OTLP_TRACE_ENV_VAR, LevelFilter::DEBUG, otlp_traces)) + .build() + } + /// Initialise the configured tracing subscribers, returning a guard that /// will shutdown the subscribers when dropped. /// @@ -606,6 +655,69 @@ fn env_filter_builder(env_var: &str, default_directive: impl Into) -> .from_env_lossy() } +/// Contains options which can be passed to [`Tracing::pre_configured()`]. +/// +/// Additionally, this struct can be used as operator CLI arguments. This functionality is only +/// available if the feature `clap` is enabled. +#[cfg_attr(feature = "clap", derive(clap::Args, PartialEq, Eq))] +#[derive(Debug, Default)] +pub struct TelemetryOptions { + /// Disable console output. + #[cfg_attr(feature = "clap", arg(long, env))] + pub no_console_output: bool, + + /// Enable logging to rolling files located in the specified DIRECTORY. + #[cfg_attr( + feature = "clap", + arg( + long, + env = "ROLLING_LOGS_DIR", + value_name = "DIRECTORY", + group = "rolling_logs_group" + ) + )] + pub rolling_logs: Option, + + /// Time PERIOD after which log files are rolled over. + #[cfg_attr( + feature = "clap", + arg(long, env, value_name = "PERIOD", requires = "rolling_logs_group") + )] + pub rolling_logs_period: Option, + + /// Enable exporting traces via OTLP. + #[cfg_attr(feature = "clap", arg(long, env))] + pub otlp_traces: bool, + + /// Enable exporting logs via OTLP. + #[cfg_attr(feature = "clap", arg(long, env))] + pub otlp_logs: bool, +} + +/// Supported periods when the log file is rolled over. +#[cfg_attr(feature = "clap", derive(clap::ValueEnum))] +#[derive(Clone, Debug, Default, PartialEq, Eq, strum::Display, strum::EnumString)] +#[allow(missing_docs)] +pub enum RollingPeriod { + Minutely, + Hourly, + Daily, + + #[default] + Never, +} + +impl From for Rotation { + fn from(value: RollingPeriod) -> Self { + match value { + RollingPeriod::Minutely => Self::MINUTELY, + RollingPeriod::Hourly => Self::HOURLY, + RollingPeriod::Daily => Self::DAILY, + RollingPeriod::Never => Self::NEVER, + } + } +} + #[cfg(test)] mod test { use std::path::PathBuf; diff --git a/crates/stackable-telemetry/src/tracing/settings/file_log.rs b/crates/stackable-telemetry/src/tracing/settings/file_log.rs index 60ba9f046..60fb21f86 100644 --- a/crates/stackable-telemetry/src/tracing/settings/file_log.rs +++ b/crates/stackable-telemetry/src/tracing/settings/file_log.rs @@ -57,8 +57,8 @@ pub struct FileLogSettingsBuilder { impl FileLogSettingsBuilder { /// Set file rotation period. - pub fn with_rotation_period(mut self, rotation_period: Rotation) -> Self { - self.rotation_period = rotation_period; + pub fn with_rotation_period(mut self, rotation_period: impl Into) -> Self { + self.rotation_period = rotation_period.into(); self } From faf920808755382c36be9d72de8beb30dd827238 Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 11:14:14 +0200 Subject: [PATCH 02/15] test: Add unit test for Tracing::pre_configured --- crates/stackable-telemetry/src/tracing/mod.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 8c0fdca81..8e4d6faac 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -912,9 +912,17 @@ mod test { })) .build(); - assert!(tracing_builder.console_log_settings.is_enabled()); - assert!(tracing_builder.file_log_settings.is_enabled()); - assert!(tracing_builder.otlp_trace_settings.is_enabled()); - assert!(tracing_builder.otlp_log_settings.is_disabled()); + + #[test] + fn pre_configured() { + let tracing = Tracing::pre_configured("test", TelemetryOptions { + no_console_output: false, + rolling_logs: None, + rolling_logs_period: None, + otlp_traces: true, + otlp_logs: false, + }); + + assert!(tracing.otlp_trace_settings.is_enabled()); } } From 11d1622409fbe605f4624bfce85f57c541b8b8af Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 11:14:56 +0200 Subject: [PATCH 03/15] chore: Update variable name used in unit test --- crates/stackable-telemetry/src/tracing/mod.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 8e4d6faac..904fe9470 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -887,7 +887,7 @@ mod test { let enable_otlp_trace = true; let enable_otlp_log = false; - let tracing_builder = Tracing::builder() + let tracing_guard = Tracing::builder() .service_name("test") .with_console_output(enable_console_output.then(|| { Settings::builder() @@ -912,6 +912,11 @@ mod test { })) .build(); + assert!(tracing_guard.console_log_settings.is_enabled()); + assert!(tracing_guard.file_log_settings.is_enabled()); + assert!(tracing_guard.otlp_trace_settings.is_enabled()); + assert!(tracing_guard.otlp_log_settings.is_disabled()); + } #[test] fn pre_configured() { From 36010e8eb5f656f64f61edfff7fbf28ced22ab2c Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 11:16:07 +0200 Subject: [PATCH 04/15] docs: Add doc comments for Tracing::pre_configured --- crates/stackable-telemetry/src/tracing/mod.rs | 40 ++++++++++++++++++- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 904fe9470..3546e5b84 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -90,7 +90,43 @@ pub enum Error { /// } /// ``` /// -/// ## Basic configuration +/// ## Pre-configured Tracing Instance +/// +/// There are two different styles to configure a [`Tracing`] instance: Using an opinionated pre- +/// configured instance or a fully customizable builder. The first option should be suited for +/// pretty much all operators by using sane defaults and applying best practices out-of-the-box. +/// [`Tracing::pre_configured`] lists details about environment variables, filter levels and +/// defaults used. +/// +/// ``` +/// use stackable_telemetry::tracing::{Tracing, TelemetryOptions, Error}; +/// +/// #[tokio::main] +/// async fn main() -> Result<(), Error> { +/// let options = TelemetryOptions { +/// no_console_output: false, +/// rolling_logs: None, +/// rolling_logs_period: None, +/// otlp_traces: true, +/// otlp_logs: true, +/// } +/// +/// let _tracing_guard = Tracing::pre_configured("test", options).init()?; +/// +/// tracing::info!("log a message"); +/// +/// Ok(()) +/// } +/// ``` +/// +/// ## Builders +/// +/// When choosing the builder, there are two different styles to configure individual subscribers: +/// Using the sophisticated [`SettingsBuilder`] or the simplified tuple style for basic +/// configuration. Currently, three different subscribers are supported: console output, OTLP log +/// export, and OTLP trace export. +/// +/// ### Basic Configuration /// /// A basic configuration of subscribers can be done by using 2-tuples or 3-tuples, also called /// doubles and triples. Using tuples, the subscriber can be enabled/disabled and it's environment @@ -120,7 +156,7 @@ pub enum Error { /// } /// ``` /// -/// ## Advanced configuration +/// ### Advanced Configuration /// /// More advanced configurations can be done via the [`Settings::builder`] function. Each /// subscriber provides specific settings based on a common set of options. These options can be From 3d44b9ec79f6392973ff31ab04c3b7eca723018b Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 11:16:54 +0200 Subject: [PATCH 05/15] chore(docs): Fixup various doc comments --- crates/stackable-telemetry/src/tracing/mod.rs | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 3546e5b84..e8cb246d7 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -62,13 +62,11 @@ pub enum Error { /// /// # Usage /// -/// There are two different styles to configure individual subscribers: Using the sophisticated -/// [`SettingsBuilder`] or the simplified tuple style for basic configuration. Currently, three -/// different subscribers are supported: console output, OTLP log export, and OTLP trace export. +/// ## Tracing Guard /// -/// The subscribers are active as long as the tracing guard returned by [`Tracing::init`] is in -/// scope and not dropped. Dropping it results in subscribers being shut down, which can lead to -/// loss of telemetry data when done before exiting the application. This is why it is important +/// The configured subscribers are active as long as the tracing guard returned by [`Tracing::init`] +/// is in scope and not dropped. Dropping it results in subscribers being shut down, which can lead +/// to loss of telemetry data when done before exiting the application. This is why it is important /// to hold onto the guard as long as required. /// ///
@@ -178,26 +176,26 @@ pub enum Error { /// .service_name("test") /// .with_console_output( /// Settings::builder() -/// .with_environment_variable("TEST_CONSOLE") +/// .with_environment_variable("CONSOLE_LOG") /// .with_default_level(LevelFilter::INFO) /// .build() /// ) /// .with_file_output( /// Settings::builder() -/// .with_environment_variable("TEST_FILE_LOG") +/// .with_environment_variable("FILE_LOG") /// .with_default_level(LevelFilter::INFO) -/// .file_log_settings_builder("/tmp/logs", "tracing-rs.log") +/// .file_log_settings_builder("/tmp/logs", "operator.log") /// .build() /// ) /// .with_otlp_log_exporter(otlp_log_flag.then(|| { /// Settings::builder() -/// .with_environment_variable("TEST_OTLP_LOG") +/// .with_environment_variable("OTLP_LOG") /// .with_default_level(LevelFilter::DEBUG) /// .build() /// })) /// .with_otlp_trace_exporter( /// Settings::builder() -/// .with_environment_variable("TEST_OTLP_TRACE") +/// .with_environment_variable("OTLP_TRACE") /// .with_default_level(LevelFilter::TRACE) /// .build() /// ) @@ -334,7 +332,7 @@ impl Tracing { .build() } - /// Initialise the configured tracing subscribers, returning a guard that + /// Initialize the configured tracing subscribers, returning a guard that /// will shutdown the subscribers when dropped. /// ///
From 2c4fd20cf66b2289f25ddbc0c83ba285ba42d3b2 Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 11:27:51 +0200 Subject: [PATCH 06/15] chore: Fix doc comment references --- crates/stackable-telemetry/src/tracing/mod.rs | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index e8cb246d7..08a41b490 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -583,10 +583,8 @@ impl TracingBuilder { impl TracingBuilder { /// Enable the console output tracing subscriber and set the default - /// [`LevelFilter`][1] which is overridable through the given environment + /// [`LevelFilter`] which is overridable through the given environment /// variable. - /// - /// [1]: tracing_subscriber::filter::LevelFilter pub fn with_console_output( self, console_log_settings: impl Into, @@ -602,10 +600,8 @@ impl TracingBuilder { } /// Enable the file output tracing subscriber and set the default - /// [`LevelFilter`][1] which is overridable through the given environment + /// [`LevelFilter`] which is overridable through the given environment /// variable. - /// - /// [1]: tracing_subscriber::filter::LevelFilter pub fn with_file_output( self, file_log_settings: impl Into, @@ -620,13 +616,11 @@ impl TracingBuilder { } } - /// Enable the OTLP logging subscriber and set the default [`LevelFilter`][1] + /// Enable the OTLP logging subscriber and set the default [`LevelFilter`] /// which is overridable through the given environment variable. /// /// You can configure the OTLP log exports through the variables defined /// in the opentelemetry crates. See [`Tracing`]. - /// - /// [1]: tracing_subscriber::filter::LevelFilter pub fn with_otlp_log_exporter( self, otlp_log_settings: impl Into, @@ -641,13 +635,11 @@ impl TracingBuilder { } } - /// Enable the OTLP tracing subscriber and set the default [`LevelFilter`][1] + /// Enable the OTLP tracing subscriber and set the default [`LevelFilter`] /// which is overridable through the given environment variable. /// /// You can configure the OTLP trace exports through the variables defined /// in the opentelemetry crates. See [`Tracing`]. - /// - /// [1]: tracing_subscriber::filter::LevelFilter pub fn with_otlp_trace_exporter( self, otlp_trace_settings: impl Into, From d3511c568292d1e16451113e3b1983b982353e00 Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 11:35:36 +0200 Subject: [PATCH 07/15] refactor: Use stackable_telemetry::TelemetryOptions --- Cargo.lock | 1 + crates/stackable-operator/Cargo.toml | 1 + crates/stackable-operator/src/cli.rs | 48 ++-------------------------- 3 files changed, 4 insertions(+), 46 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index e7def0a4d..de3a0bce9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3209,6 +3209,7 @@ dependencies = [ "snafu 0.8.5", "stackable-operator-derive", "stackable-shared", + "stackable-telemetry", "strum", "tempfile", "time", diff --git a/crates/stackable-operator/Cargo.toml b/crates/stackable-operator/Cargo.toml index 95fd8a278..b0d0f2341 100644 --- a/crates/stackable-operator/Cargo.toml +++ b/crates/stackable-operator/Cargo.toml @@ -11,6 +11,7 @@ repository.workspace = true time = ["dep:time"] [dependencies] +stackable-telemetry = { path = "../stackable-telemetry", features = ["clap"]} stackable-operator-derive = { path = "../stackable-operator-derive" } stackable-shared = { path = "../stackable-shared" } diff --git a/crates/stackable-operator/src/cli.rs b/crates/stackable-operator/src/cli.rs index a415e9a15..66e6441ae 100644 --- a/crates/stackable-operator/src/cli.rs +++ b/crates/stackable-operator/src/cli.rs @@ -108,13 +108,13 @@ //! use std::{ ffi::OsStr, - ops::Deref, path::{Path, PathBuf}, }; use clap::Args; use product_config::ProductConfigManager; use snafu::{ResultExt, Snafu}; +use stackable_telemetry::tracing::TelemetryOptions; use crate::{namespace::WatchNamespace, utils::cluster_info::KubernetesClusterInfoOpts}; @@ -219,7 +219,7 @@ pub struct ProductOperatorRun { pub watch_namespace: WatchNamespace, #[command(flatten)] - pub telemetry_arguments: TelemetryArguments, + pub telemetry_arguments: TelemetryOptions, #[command(flatten)] pub cluster_info_opts: KubernetesClusterInfoOpts, @@ -280,50 +280,6 @@ impl ProductConfigPath { } } -#[derive(Debug, Default, PartialEq, Eq, Args)] -pub struct TelemetryArguments { - /// Disable console output. - #[arg(long, env)] - pub no_console_output: bool, - - /// Enable logging to rolling files located in the specified DIRECTORY. - #[arg(long, env, value_name = "DIRECTORY", group = "rolling_logs_group")] - pub rolling_logs: Option, - - /// Time PERIOD after which log files are rolled over. - #[arg(long, env, value_name = "PERIOD", requires = "rolling_logs_group")] - pub rolling_logs_period: Option, - - /// Enable exporting traces via OTLP. - #[arg(long, env)] - pub otlp_traces: bool, - - /// Enable exporting logs via OTLP. - #[arg(long, env)] - pub otlp_logs: bool, -} - -#[derive(Clone, Debug, PartialEq, Eq, strum::Display, strum::EnumString, clap::ValueEnum)] -pub enum RollingPeriod { - Minutely, - Hourly, - Daily, - Never, -} - -impl Deref for RollingPeriod { - type Target = tracing_appender::rolling::Rotation; - - fn deref(&self) -> &Self::Target { - match self { - RollingPeriod::Minutely => &tracing_appender::rolling::Rotation::MINUTELY, - RollingPeriod::Hourly => &tracing_appender::rolling::Rotation::HOURLY, - RollingPeriod::Daily => &tracing_appender::rolling::Rotation::DAILY, - RollingPeriod::Never => &tracing_appender::rolling::Rotation::NEVER, - } - } -} - #[cfg(test)] mod tests { use std::{env, fs::File}; From c5efdfadfc3458efe5b3be5278292cad805cc18d Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 11:47:33 +0200 Subject: [PATCH 08/15] chore: Update changelogs --- crates/stackable-operator/CHANGELOG.md | 8 ++++++++ crates/stackable-telemetry/CHANGELOG.md | 6 ++++++ 2 files changed, 14 insertions(+) diff --git a/crates/stackable-operator/CHANGELOG.md b/crates/stackable-operator/CHANGELOG.md index ade1b3e15..d7c4c312f 100644 --- a/crates/stackable-operator/CHANGELOG.md +++ b/crates/stackable-operator/CHANGELOG.md @@ -8,7 +8,15 @@ All notable changes to this project will be documented in this file. - BREAKING: Inject vector aggregator address into vector config file using an environment variable ([#1000]). +### Changed + +- BREAKING: Remove `cli::TelemetryArguments` and `cli::RollingPeriod` which are both replaced by + types from `stackable_telemetry` ([#1001]). +- BREAKING: The `ProductOperatorRun` struct now uses `stackable_telemetry::tracing::TelemetryOptions` + for the `telemetry_arguments` field ([#1001]). + [#1000]: https://github.com/stackabletech/operator-rs/pull/1000 +[#1001]: https://github.com/stackabletech/operator-rs/pull/1001 ## [0.89.1] - 2025-04-02 diff --git a/crates/stackable-telemetry/CHANGELOG.md b/crates/stackable-telemetry/CHANGELOG.md index 2df9840d9..0cad1c816 100644 --- a/crates/stackable-telemetry/CHANGELOG.md +++ b/crates/stackable-telemetry/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +### Added + +- Add new `Tracing::pre_configured` method ([#1001]). + +[#1001]: https://github.com/stackabletech/operator-rs/pull/1001 + ## [0.4.0] - 2025-04-02 ### Added From c8c1b6074332eeb3d943829d2ebb0e1f1b01d398 Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 11:54:40 +0200 Subject: [PATCH 09/15] chore: Fix doc tests --- crates/stackable-operator/src/cli.rs | 8 +++----- crates/stackable-telemetry/src/tracing/mod.rs | 2 +- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/crates/stackable-operator/src/cli.rs b/crates/stackable-operator/src/cli.rs index 66e6441ae..f3a505eb0 100644 --- a/crates/stackable-operator/src/cli.rs +++ b/crates/stackable-operator/src/cli.rs @@ -165,10 +165,8 @@ pub enum Command { /// ```rust /// # use stackable_operator::cli::{Command, ProductOperatorRun, ProductConfigPath}; /// use clap::Parser; -/// use stackable_operator::{ -/// cli::TelemetryArguments, -/// namespace::WatchNamespace, -/// }; +/// use stackable_operator::namespace::WatchNamespace; +/// use stackable_telemetry::tracing::TelemetryOptions; /// /// #[derive(clap::Parser, Debug, PartialEq, Eq)] /// struct Run { @@ -184,7 +182,7 @@ pub enum Command { /// common: ProductOperatorRun { /// product_config: ProductConfigPath::from("bar".as_ref()), /// watch_namespace: WatchNamespace::One("foobar".to_string()), -/// telemetry_arguments: TelemetryArguments::default(), +/// telemetry_arguments: TelemetryOptions::default(), /// cluster_info_opts: Default::default(), /// }, /// })); diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 08a41b490..f31ad4c21 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -107,7 +107,7 @@ pub enum Error { /// rolling_logs_period: None, /// otlp_traces: true, /// otlp_logs: true, -/// } +/// }; /// /// let _tracing_guard = Tracing::pre_configured("test", options).init()?; /// From 1e95f7e040882c7f66644dfba80ab8fe492e6b08 Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 15:07:00 +0200 Subject: [PATCH 10/15] chore: Change filename suffix to "tracing-rs.json" --- crates/stackable-telemetry/src/tracing/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index f31ad4c21..11f52391b 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -285,7 +285,7 @@ impl Tracing { /// The environment variable used to set the rolling file log level filter. pub const FILE_LOG_ENV_VAR: &str = "FILE_LOG"; /// The filename used for the rolling file logs. - pub const FILE_LOG_NAME: &str = "operator.log"; + pub const FILE_LOG_SUFFIX: &str = "tracing-rs.json"; /// The environment variable used to set the OTLP log level filter. pub const OTLP_LOG_ENV_VAR: &str = "OTLP_LOG"; /// The environment variable used to set the OTLP trace level filter. @@ -323,7 +323,7 @@ impl Tracing { Settings::builder() .with_environment_variable(Self::FILE_LOG_ENV_VAR) .with_default_level(LevelFilter::INFO) - .file_log_settings_builder(log_directory, Self::FILE_LOG_NAME) + .file_log_settings_builder(log_directory, Self::FILE_LOG_SUFFIX) .with_rotation_period(rolling_logs_period) .build() })) From 82c14ad810230e1c0d88411c50b72e3d3e18f363 Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 16:04:17 +0200 Subject: [PATCH 11/15] docs: Document default env vars, level filters and default values --- crates/stackable-telemetry/src/tracing/mod.rs | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 11f52391b..5264941bb 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -299,8 +299,19 @@ impl Tracing { /// Creates an returns a pre-configured [`Tracing`] instance which can be initialized by /// calling [`Tracing::init()`]. /// - /// If `rolling_logs_period` is [`None`], this function will use a default value of - /// [`RollingPeriod::Never`]. + /// ### Environment Variables and Default Levels + /// + /// | Level Filter for | Environment Variable | Default Level | + /// | ---------------- | ------------------------------------------ | ------------- | + /// | Console logs | [`CONSOLE_LOG`](Self::CONSOLE_LOG_ENV_VAR) | `INFO` | + /// | File logs | [`FILE_LOG`](Self::FILE_LOG_ENV_VAR) | `INFO` | + /// | OTLP logs | [`OTLP_LOG`](Self::OTLP_LOG_ENV_VAR) | `DEBUG` | + /// | OTLP traces | [`OTLP_TRACE`](Self::OTLP_TRACE_ENV_VAR) | `DEBUG` | + /// + /// ### Default Values + /// + /// - If `rolling_logs_period` is [`None`], this function will use a default value of + /// [`RollingPeriod::Never`]. pub fn pre_configured(service_name: &'static str, options: TelemetryOptions) -> Self { let TelemetryOptions { no_console_output, From 861ded97bb2d9f49232a892afba294ae88e606ae Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 7 Apr 2025 16:30:19 +0200 Subject: [PATCH 12/15] chore(stackable-telemetry): Adjust changelog --- crates/stackable-telemetry/CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/crates/stackable-telemetry/CHANGELOG.md b/crates/stackable-telemetry/CHANGELOG.md index 0cad1c816..d46471289 100644 --- a/crates/stackable-telemetry/CHANGELOG.md +++ b/crates/stackable-telemetry/CHANGELOG.md @@ -7,6 +7,13 @@ All notable changes to this project will be documented in this file. ### Added - Add new `Tracing::pre_configured` method ([#1001]). + - Add `TelemetryOptions` struct and `RollingPeriod` enum + - Add `clap` feature to enable `TelemetryOptions` being used as CLI arguments + +### Changed + +- BREAKING: Change `FileLogSettingsBuilder::with_rotation_period` to take `impl Into` + instead of `Rotation` ([#1001]). [#1001]: https://github.com/stackabletech/operator-rs/pull/1001 From 6453e5db4aeab5ad1e0377acdcfb4fe1641a0573 Mon Sep 17 00:00:00 2001 From: Techassi Date: Tue, 8 Apr 2025 12:24:54 +0200 Subject: [PATCH 13/15] chore: Change level for OTLP logs and traces to INFO Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> --- crates/stackable-telemetry/src/tracing/mod.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 5264941bb..041d70d5b 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -305,8 +305,8 @@ impl Tracing { /// | ---------------- | ------------------------------------------ | ------------- | /// | Console logs | [`CONSOLE_LOG`](Self::CONSOLE_LOG_ENV_VAR) | `INFO` | /// | File logs | [`FILE_LOG`](Self::FILE_LOG_ENV_VAR) | `INFO` | - /// | OTLP logs | [`OTLP_LOG`](Self::OTLP_LOG_ENV_VAR) | `DEBUG` | - /// | OTLP traces | [`OTLP_TRACE`](Self::OTLP_TRACE_ENV_VAR) | `DEBUG` | + /// | OTLP logs | [`OTLP_LOG`](Self::OTLP_LOG_ENV_VAR) | `INFO` | + /// | OTLP traces | [`OTLP_TRACE`](Self::OTLP_TRACE_ENV_VAR) | `INFO` | /// /// ### Default Values /// @@ -338,8 +338,8 @@ impl Tracing { .with_rotation_period(rolling_logs_period) .build() })) - .with_otlp_log_exporter((Self::OTLP_LOG_ENV_VAR, LevelFilter::DEBUG, otlp_logs)) - .with_otlp_trace_exporter((Self::OTLP_TRACE_ENV_VAR, LevelFilter::DEBUG, otlp_traces)) + .with_otlp_log_exporter((Self::OTLP_LOG_ENV_VAR, LevelFilter::INFO, otlp_logs)) + .with_otlp_trace_exporter((Self::OTLP_TRACE_ENV_VAR, LevelFilter::INFO, otlp_traces)) .build() } From 5fe969d0c05b29e6f40b4d14492d09240fd4fe1f Mon Sep 17 00:00:00 2001 From: Techassi Date: Tue, 8 Apr 2025 13:46:55 +0200 Subject: [PATCH 14/15] docs: Add clap specific example for TelemetryOptions --- crates/stackable-telemetry/src/tracing/mod.rs | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 041d70d5b..19bd7e57d 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -8,6 +8,8 @@ use std::path::PathBuf; +#[cfg_attr(feature = "clap", cfg(doc))] +use clap; use opentelemetry::trace::TracerProvider; use opentelemetry_appender_tracing::layer::OpenTelemetryTracingBridge; use opentelemetry_otlp::{LogExporter, SpanExporter}; @@ -117,6 +119,9 @@ pub enum Error { /// } /// ``` /// +/// Also see the documentation for [`TelemetryOptions`] which details how it can be used as CLI +/// arguments via [`clap`]. +/// /// ## Builders /// /// When choosing the builder, there are two different styles to configure individual subscribers: @@ -305,8 +310,8 @@ impl Tracing { /// | ---------------- | ------------------------------------------ | ------------- | /// | Console logs | [`CONSOLE_LOG`](Self::CONSOLE_LOG_ENV_VAR) | `INFO` | /// | File logs | [`FILE_LOG`](Self::FILE_LOG_ENV_VAR) | `INFO` | - /// | OTLP logs | [`OTLP_LOG`](Self::OTLP_LOG_ENV_VAR) | `INFO` | - /// | OTLP traces | [`OTLP_TRACE`](Self::OTLP_TRACE_ENV_VAR) | `INFO` | + /// | OTLP logs | [`OTLP_LOG`](Self::OTLP_LOG_ENV_VAR) | `INFO` | + /// | OTLP traces | [`OTLP_TRACE`](Self::OTLP_TRACE_ENV_VAR) | `INFO` | /// /// ### Default Values /// @@ -696,6 +701,25 @@ fn env_filter_builder(env_var: &str, default_directive: impl Into) -> /// /// Additionally, this struct can be used as operator CLI arguments. This functionality is only /// available if the feature `clap` is enabled. +/// +#[cfg_attr( + feature = "clap", + doc = r#" +``` +# use stackable_telemetry::tracing::TelemetryOptions; +use clap::Parser; + +#[derive(Parser)] +struct Cli { + #[arg(short, long)] + namespace: String, + + #[clap(flatten)] + telemetry_arguments: TelemetryOptions, +} +``` +"# +)] #[cfg_attr(feature = "clap", derive(clap::Args, PartialEq, Eq))] #[derive(Debug, Default)] pub struct TelemetryOptions { From 3cd755f46bbb2f6657ccdbbac4fe0a1fed971a46 Mon Sep 17 00:00:00 2001 From: Techassi Date: Tue, 8 Apr 2025 13:54:24 +0200 Subject: [PATCH 15/15] chore: Fix changelog --- crates/stackable-operator/CHANGELOG.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/crates/stackable-operator/CHANGELOG.md b/crates/stackable-operator/CHANGELOG.md index d3b43bf71..37096f4f3 100644 --- a/crates/stackable-operator/CHANGELOG.md +++ b/crates/stackable-operator/CHANGELOG.md @@ -4,12 +4,6 @@ All notable changes to this project will be documented in this file. ## [Unreleased] -## [0.90.0] - 2025-04-07 - -### Added - -- BREAKING: Inject vector aggregator address into vector config file using an environment variable ([#1000]). - ### Changed - BREAKING: Remove `cli::TelemetryArguments` and `cli::RollingPeriod` which are both replaced by @@ -17,9 +11,16 @@ All notable changes to this project will be documented in this file. - BREAKING: The `ProductOperatorRun` struct now uses `stackable_telemetry::tracing::TelemetryOptions` for the `telemetry_arguments` field ([#1001]). -[#1000]: https://github.com/stackabletech/operator-rs/pull/1000 [#1001]: https://github.com/stackabletech/operator-rs/pull/1001 +## [0.90.0] - 2025-04-07 + +### Added + +- BREAKING: Inject vector aggregator address into vector config file using an environment variable ([#1000]). + +[#1000]: https://github.com/stackabletech/operator-rs/pull/1000 + ## [0.89.1] - 2025-04-02 ### Changed