diff --git a/crates/stackable-operator/CHANGELOG.md b/crates/stackable-operator/CHANGELOG.md index f9ef629c3..a3db6d45d 100644 --- a/crates/stackable-operator/CHANGELOG.md +++ b/crates/stackable-operator/CHANGELOG.md @@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +### Changed + +- BREAKING: Update and align telemetry related CLI arguments of `ProductOperatorRun`, see detailed + changelog [here](../stackable-telemetry/CHANGELOG.md) ([#1009]). + +[#1009]: https://github.com/stackabletech/operator-rs/pull/1009 + ## [0.91.1] - 2025-04-09 ### Added diff --git a/crates/stackable-telemetry/CHANGELOG.md b/crates/stackable-telemetry/CHANGELOG.md index 927b913f9..9e3c553cd 100644 --- a/crates/stackable-telemetry/CHANGELOG.md +++ b/crates/stackable-telemetry/CHANGELOG.md @@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +### Changed + +- BREAKING: Update and align telemetry related CLI arguments in `TelemetryOptions` ([#1009]). + - `--console-log-disabled` instead of `--no-console-output`. + - `--file-log-directory` instead of `--rolling-logs`. + - `--file-log-rotation-period` instead of `--rolling-logs-period`. + - `--otel-log-exporter-enabled` instead of `--otlp-logs`. + - `--otel-trace-exporter-enabled` instead of `--otlp-traces`. +- BREAKING: Update and align telemetry related environment variables ([#1009]). + - `CONSOLE_LOG_LEVEL` instead of `CONSOLE_LOG`. + - `FILE_LOG_LEVEL` instead of `FILE_LOG`. + - `OTEL_LOG_EXPORTER_LEVEL` instead of `OTLP_LOG`. + - `OTEL_TRACE_EXPORTER_LEVEL` instead of `OTLP_TRACE`. + +[#1009]: https://github.com/stackabletech/operator-rs/pull/1009 + ## [0.5.0] - 2025-04-08 ### Added diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 19bd7e57d..708aac2a1 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -104,11 +104,11 @@ pub enum 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, +/// console_log_disabled: false, +/// file_log_directory: None, +/// file_log_rotation_period: None, +/// otel_trace_exporter_enabled: true, +/// otel_log_exporter_enabled: true, /// }; /// /// let _tracing_guard = Tracing::pre_configured("test", options).init()?; @@ -120,7 +120,9 @@ pub enum Error { /// ``` /// /// Also see the documentation for [`TelemetryOptions`] which details how it can be used as CLI -/// arguments via [`clap`]. +/// arguments via [`clap`]. Additionally see [this section](#environment-variables-and-cli-arguments) +/// in the docs for a full list of environment variables and CLI arguments used by the pre-configured +/// instance. /// /// ## Builders /// @@ -213,6 +215,29 @@ pub enum Error { /// } /// ``` /// +/// ## Environment Variables and CLI Arguments +/// +/// ### Console logs +/// +/// - `CONSOLE_LOG_DISABLED` (`--console-log-disabled`): Disables console logs when set to `true`. +/// - `CONSOLE_LOG_LEVEL`: Set the log level for the console logs. +/// +/// ### File logs +/// +/// - `FILE_LOG_DIRECTORY` (`--file-log-directory`): Enable the file logs and set the file log directory. +/// - `FILE_LOG_ROTATION_PERIOD` (`--file-log-rotation-period`): Set the rotation period of log files +/// - `FILE_LOG_LEVEL`: Set the log level for file logs +/// +/// ### OTEL logs +/// +/// - `OTEL_LOG_EXPORTER_ENABLED` (`--otel-log-exporter-enabled`): Enable exporting OTEL logs +/// - `OTEL_LOG_EXPORTER_LEVEL`: Set the log level for OTEL logs +/// +/// ### OTEL traces +/// +/// - `OTEL_TRACE_EXPORTER_ENABLED` (`--otel-trace-exporter-enabled`): Enable exporting OTEL traces +/// - `OTEL_TRACE_EXPORTER_LEVEL`: Set the log level for OTEL traces +/// /// # Additional Configuration /// /// You can configure the OTLP trace and log exports through the variables defined in the opentelemetry crates: @@ -286,15 +311,15 @@ 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"; + pub const CONSOLE_LOG_LEVEL_ENV: &str = "CONSOLE_LOG_LEVEL"; /// The environment variable used to set the rolling file log level filter. - pub const FILE_LOG_ENV_VAR: &str = "FILE_LOG"; + pub const FILE_LOG_LEVEL_ENV: &str = "FILE_LOG_LEVEL"; /// The filename used for the rolling file logs. 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. - pub const OTLP_TRACE_ENV_VAR: &str = "OTLP_TRACE"; + /// The environment variable used to set the OTEL log level filter. + pub const OTEL_LOG_EXPORTER_LEVEL_ENV: &str = "OTEL_LOG_EXPORTER_LEVEL"; + /// The environment variable used to set the OTEL trace level filter. + pub const OTEL_TRACE_EXPORTER_LEVEL_ENV: &str = "OTEL_TRACE_EXPORTER_LEVEL"; /// Creates and returns a [`TracingBuilder`]. pub fn builder() -> TracingBuilder { @@ -304,47 +329,56 @@ impl Tracing { /// Creates an returns a pre-configured [`Tracing`] instance which can be initialized by /// calling [`Tracing::init()`]. /// - /// ### Environment Variables and Default Levels + /// Also see [this section](#environment-variables-and-cli-arguments) in the docs for all full + /// list of environment variables and CLI arguments used by the pre-configured instance. + /// + /// ### 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) | `INFO` | - /// | OTLP traces | [`OTLP_TRACE`](Self::OTLP_TRACE_ENV_VAR) | `INFO` | + /// - Console logs: INFO + /// - File logs: INFO + /// - OTEL logs: INFO + /// - OTEL traces: INFO /// /// ### Default Values /// /// - If `rolling_logs_period` is [`None`], this function will use a default value of - /// [`RollingPeriod::Never`]. + /// [`RotationPeriod::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, + console_log_disabled, + file_log_directory, + file_log_rotation_period, + otel_trace_exporter_enabled, + otel_log_exporter_enabled, } = options; - let rolling_logs_period = rolling_logs_period.unwrap_or_default(); + let file_log_rotation_period = file_log_rotation_period.unwrap_or_default(); Self::builder() .service_name(service_name) .with_console_output(( - Self::CONSOLE_LOG_ENV_VAR, + Self::CONSOLE_LOG_LEVEL_ENV, LevelFilter::INFO, - !no_console_output, + !console_log_disabled, )) - .with_file_output(rolling_logs.map(|log_directory| { + .with_file_output(file_log_directory.map(|log_directory| { Settings::builder() - .with_environment_variable(Self::FILE_LOG_ENV_VAR) + .with_environment_variable(Self::FILE_LOG_LEVEL_ENV) .with_default_level(LevelFilter::INFO) .file_log_settings_builder(log_directory, Self::FILE_LOG_SUFFIX) - .with_rotation_period(rolling_logs_period) + .with_rotation_period(file_log_rotation_period) .build() })) - .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)) + .with_otlp_log_exporter(( + Self::OTEL_LOG_EXPORTER_LEVEL_ENV, + LevelFilter::INFO, + otel_log_exporter_enabled, + )) + .with_otlp_trace_exporter(( + Self::OTEL_TRACE_EXPORTER_LEVEL_ENV, + LevelFilter::INFO, + otel_trace_exporter_enabled, + )) .build() } @@ -723,43 +757,39 @@ struct Cli { #[cfg_attr(feature = "clap", derive(clap::Args, PartialEq, Eq))] #[derive(Debug, Default)] pub struct TelemetryOptions { - /// Disable console output. + /// Disable console logs. #[cfg_attr(feature = "clap", arg(long, env))] - pub no_console_output: bool, + pub console_log_disabled: bool, - /// Enable logging to rolling files located in the specified DIRECTORY. + /// Enable logging to files located in the specified DIRECTORY. #[cfg_attr( feature = "clap", - arg( - long, - env = "ROLLING_LOGS_DIR", - value_name = "DIRECTORY", - group = "rolling_logs_group" - ) + arg(long, env, value_name = "DIRECTORY", group = "file_log") )] - pub rolling_logs: Option, + pub file_log_directory: Option, /// Time PERIOD after which log files are rolled over. #[cfg_attr( feature = "clap", - arg(long, env, value_name = "PERIOD", requires = "rolling_logs_group") + arg(long, env, value_name = "PERIOD", requires = "file_log") )] - pub rolling_logs_period: Option, + pub file_log_rotation_period: Option, - /// Enable exporting traces via OTLP. + /// Enable exporting OpenTelemetry traces via OTLP. #[cfg_attr(feature = "clap", arg(long, env))] - pub otlp_traces: bool, + pub otel_trace_exporter_enabled: bool, - /// Enable exporting logs via OTLP. + /// Enable exporting OpenTelemetry logs via OTLP. #[cfg_attr(feature = "clap", arg(long, env))] - pub otlp_logs: bool, + pub otel_log_exporter_enabled: 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)] +#[strum(serialize_all = "PascalCase")] #[allow(missing_docs)] -pub enum RollingPeriod { +pub enum RotationPeriod { Minutely, Hourly, Daily, @@ -768,13 +798,13 @@ pub enum RollingPeriod { Never, } -impl From for Rotation { - fn from(value: RollingPeriod) -> Self { +impl From for Rotation { + fn from(value: RotationPeriod) -> Self { match value { - RollingPeriod::Minutely => Self::MINUTELY, - RollingPeriod::Hourly => Self::HOURLY, - RollingPeriod::Daily => Self::DAILY, - RollingPeriod::Never => Self::NEVER, + RotationPeriod::Minutely => Self::MINUTELY, + RotationPeriod::Hourly => Self::HOURLY, + RotationPeriod::Daily => Self::DAILY, + RotationPeriod::Never => Self::NEVER, } } } @@ -982,11 +1012,11 @@ mod test { #[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, + console_log_disabled: false, + file_log_directory: None, + file_log_rotation_period: None, + otel_trace_exporter_enabled: true, + otel_log_exporter_enabled: false, }); assert!(tracing.otlp_trace_settings.is_enabled());