Skip to content

Commit 63a4e45

Browse files
TechassiNickLarsenNZ
Techassi
and
NickLarsenNZ
authored
refactor!: Update telemetry related env vars and CLI args (#1009)
* refactor!: Update telemetry related env vars and CLI args * chore: Update changelogs * chore: Update doc comment * test: Fix doc test * chore: Apply suggestions from code review Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * chore: Update doc comments Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> --------- Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com>
1 parent 0f9b6f9 commit 63a4e45

File tree

3 files changed

+114
-61
lines changed

3 files changed

+114
-61
lines changed

‎crates/stackable-operator/CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
44

55
## [Unreleased]
66

7+
### Changed
8+
9+
- BREAKING: Update and align telemetry related CLI arguments of `ProductOperatorRun`, see detailed
10+
changelog [here](../stackable-telemetry/CHANGELOG.md) ([#1009]).
11+
12+
[#1009]: https://github.com/stackabletech/operator-rs/pull/1009
13+
714
## [0.91.1] - 2025-04-09
815

916
### Added

‎crates/stackable-telemetry/CHANGELOG.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
44

55
## [Unreleased]
66

7+
### Changed
8+
9+
- BREAKING: Update and align telemetry related CLI arguments in `TelemetryOptions` ([#1009]).
10+
- `--console-log-disabled` instead of `--no-console-output`.
11+
- `--file-log-directory` instead of `--rolling-logs`.
12+
- `--file-log-rotation-period` instead of `--rolling-logs-period`.
13+
- `--otel-log-exporter-enabled` instead of `--otlp-logs`.
14+
- `--otel-trace-exporter-enabled` instead of `--otlp-traces`.
15+
- BREAKING: Update and align telemetry related environment variables ([#1009]).
16+
- `CONSOLE_LOG_LEVEL` instead of `CONSOLE_LOG`.
17+
- `FILE_LOG_LEVEL` instead of `FILE_LOG`.
18+
- `OTEL_LOG_EXPORTER_LEVEL` instead of `OTLP_LOG`.
19+
- `OTEL_TRACE_EXPORTER_LEVEL` instead of `OTLP_TRACE`.
20+
21+
[#1009]: https://github.com/stackabletech/operator-rs/pull/1009
22+
723
## [0.5.0] - 2025-04-08
824

925
### Added

‎crates/stackable-telemetry/src/tracing/mod.rs‎

Lines changed: 91 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -104,11 +104,11 @@ pub enum Error {
104104
/// #[tokio::main]
105105
/// async fn main() -> Result<(), Error> {
106106
/// let options = TelemetryOptions {
107-
/// no_console_output: false,
108-
/// rolling_logs: None,
109-
/// rolling_logs_period: None,
110-
/// otlp_traces: true,
111-
/// otlp_logs: true,
107+
/// console_log_disabled: false,
108+
/// file_log_directory: None,
109+
/// file_log_rotation_period: None,
110+
/// otel_trace_exporter_enabled: true,
111+
/// otel_log_exporter_enabled: true,
112112
/// };
113113
///
114114
/// let _tracing_guard = Tracing::pre_configured("test", options).init()?;
@@ -120,7 +120,9 @@ pub enum Error {
120120
/// ```
121121
///
122122
/// Also see the documentation for [`TelemetryOptions`] which details how it can be used as CLI
123-
/// arguments via [`clap`].
123+
/// arguments via [`clap`]. Additionally see [this section](#environment-variables-and-cli-arguments)
124+
/// in the docs for a full list of environment variables and CLI arguments used by the pre-configured
125+
/// instance.
124126
///
125127
/// ## Builders
126128
///
@@ -213,6 +215,29 @@ pub enum Error {
213215
/// }
214216
/// ```
215217
///
218+
/// ## Environment Variables and CLI Arguments
219+
///
220+
/// ### Console logs
221+
///
222+
/// - `CONSOLE_LOG_DISABLED` (`--console-log-disabled`): Disables console logs when set to `true`.
223+
/// - `CONSOLE_LOG_LEVEL`: Set the log level for the console logs.
224+
///
225+
/// ### File logs
226+
///
227+
/// - `FILE_LOG_DIRECTORY` (`--file-log-directory`): Enable the file logs and set the file log directory.
228+
/// - `FILE_LOG_ROTATION_PERIOD` (`--file-log-rotation-period`): Set the rotation period of log files
229+
/// - `FILE_LOG_LEVEL`: Set the log level for file logs
230+
///
231+
/// ### OTEL logs
232+
///
233+
/// - `OTEL_LOG_EXPORTER_ENABLED` (`--otel-log-exporter-enabled`): Enable exporting OTEL logs
234+
/// - `OTEL_LOG_EXPORTER_LEVEL`: Set the log level for OTEL logs
235+
///
236+
/// ### OTEL traces
237+
///
238+
/// - `OTEL_TRACE_EXPORTER_ENABLED` (`--otel-trace-exporter-enabled`): Enable exporting OTEL traces
239+
/// - `OTEL_TRACE_EXPORTER_LEVEL`: Set the log level for OTEL traces
240+
///
216241
/// # Additional Configuration
217242
///
218243
/// You can configure the OTLP trace and log exports through the variables defined in the opentelemetry crates:
@@ -286,15 +311,15 @@ pub struct Tracing {
286311

287312
impl Tracing {
288313
/// The environment variable used to set the console log level filter.
289-
pub const CONSOLE_LOG_ENV_VAR: &str = "CONSOLE_LOG";
314+
pub const CONSOLE_LOG_LEVEL_ENV: &str = "CONSOLE_LOG_LEVEL";
290315
/// The environment variable used to set the rolling file log level filter.
291-
pub const FILE_LOG_ENV_VAR: &str = "FILE_LOG";
316+
pub const FILE_LOG_LEVEL_ENV: &str = "FILE_LOG_LEVEL";
292317
/// The filename used for the rolling file logs.
293318
pub const FILE_LOG_SUFFIX: &str = "tracing-rs.json";
294-
/// The environment variable used to set the OTLP log level filter.
295-
pub const OTLP_LOG_ENV_VAR: &str = "OTLP_LOG";
296-
/// The environment variable used to set the OTLP trace level filter.
297-
pub const OTLP_TRACE_ENV_VAR: &str = "OTLP_TRACE";
319+
/// The environment variable used to set the OTEL log level filter.
320+
pub const OTEL_LOG_EXPORTER_LEVEL_ENV: &str = "OTEL_LOG_EXPORTER_LEVEL";
321+
/// The environment variable used to set the OTEL trace level filter.
322+
pub const OTEL_TRACE_EXPORTER_LEVEL_ENV: &str = "OTEL_TRACE_EXPORTER_LEVEL";
298323

299324
/// Creates and returns a [`TracingBuilder`].
300325
pub fn builder() -> TracingBuilder<builder_state::PreServiceName> {
@@ -304,47 +329,56 @@ impl Tracing {
304329
/// Creates an returns a pre-configured [`Tracing`] instance which can be initialized by
305330
/// calling [`Tracing::init()`].
306331
///
307-
/// ### Environment Variables and Default Levels
332+
/// Also see [this section](#environment-variables-and-cli-arguments) in the docs for all full
333+
/// list of environment variables and CLI arguments used by the pre-configured instance.
334+
///
335+
/// ### Default Levels
308336
///
309-
/// | Level Filter for | Environment Variable | Default Level |
310-
/// | ---------------- | ------------------------------------------ | ------------- |
311-
/// | Console logs | [`CONSOLE_LOG`](Self::CONSOLE_LOG_ENV_VAR) | `INFO` |
312-
/// | File logs | [`FILE_LOG`](Self::FILE_LOG_ENV_VAR) | `INFO` |
313-
/// | OTLP logs | [`OTLP_LOG`](Self::OTLP_LOG_ENV_VAR) | `INFO` |
314-
/// | OTLP traces | [`OTLP_TRACE`](Self::OTLP_TRACE_ENV_VAR) | `INFO` |
337+
/// - Console logs: INFO
338+
/// - File logs: INFO
339+
/// - OTEL logs: INFO
340+
/// - OTEL traces: INFO
315341
///
316342
/// ### Default Values
317343
///
318344
/// - If `rolling_logs_period` is [`None`], this function will use a default value of
319-
/// [`RollingPeriod::Never`].
345+
/// [`RotationPeriod::Never`].
320346
pub fn pre_configured(service_name: &'static str, options: TelemetryOptions) -> Self {
321347
let TelemetryOptions {
322-
no_console_output,
323-
rolling_logs,
324-
rolling_logs_period,
325-
otlp_traces,
326-
otlp_logs,
348+
console_log_disabled,
349+
file_log_directory,
350+
file_log_rotation_period,
351+
otel_trace_exporter_enabled,
352+
otel_log_exporter_enabled,
327353
} = options;
328354

329-
let rolling_logs_period = rolling_logs_period.unwrap_or_default();
355+
let file_log_rotation_period = file_log_rotation_period.unwrap_or_default();
330356

331357
Self::builder()
332358
.service_name(service_name)
333359
.with_console_output((
334-
Self::CONSOLE_LOG_ENV_VAR,
360+
Self::CONSOLE_LOG_LEVEL_ENV,
335361
LevelFilter::INFO,
336-
!no_console_output,
362+
!console_log_disabled,
337363
))
338-
.with_file_output(rolling_logs.map(|log_directory| {
364+
.with_file_output(file_log_directory.map(|log_directory| {
339365
Settings::builder()
340-
.with_environment_variable(Self::FILE_LOG_ENV_VAR)
366+
.with_environment_variable(Self::FILE_LOG_LEVEL_ENV)
341367
.with_default_level(LevelFilter::INFO)
342368
.file_log_settings_builder(log_directory, Self::FILE_LOG_SUFFIX)
343-
.with_rotation_period(rolling_logs_period)
369+
.with_rotation_period(file_log_rotation_period)
344370
.build()
345371
}))
346-
.with_otlp_log_exporter((Self::OTLP_LOG_ENV_VAR, LevelFilter::INFO, otlp_logs))
347-
.with_otlp_trace_exporter((Self::OTLP_TRACE_ENV_VAR, LevelFilter::INFO, otlp_traces))
372+
.with_otlp_log_exporter((
373+
Self::OTEL_LOG_EXPORTER_LEVEL_ENV,
374+
LevelFilter::INFO,
375+
otel_log_exporter_enabled,
376+
))
377+
.with_otlp_trace_exporter((
378+
Self::OTEL_TRACE_EXPORTER_LEVEL_ENV,
379+
LevelFilter::INFO,
380+
otel_trace_exporter_enabled,
381+
))
348382
.build()
349383
}
350384

@@ -723,43 +757,39 @@ struct Cli {
723757
#[cfg_attr(feature = "clap", derive(clap::Args, PartialEq, Eq))]
724758
#[derive(Debug, Default)]
725759
pub struct TelemetryOptions {
726-
/// Disable console output.
760+
/// Disable console logs.
727761
#[cfg_attr(feature = "clap", arg(long, env))]
728-
pub no_console_output: bool,
762+
pub console_log_disabled: bool,
729763

730-
/// Enable logging to rolling files located in the specified DIRECTORY.
764+
/// Enable logging to files located in the specified DIRECTORY.
731765
#[cfg_attr(
732766
feature = "clap",
733-
arg(
734-
long,
735-
env = "ROLLING_LOGS_DIR",
736-
value_name = "DIRECTORY",
737-
group = "rolling_logs_group"
738-
)
767+
arg(long, env, value_name = "DIRECTORY", group = "file_log")
739768
)]
740-
pub rolling_logs: Option<PathBuf>,
769+
pub file_log_directory: Option<PathBuf>,
741770

742771
/// Time PERIOD after which log files are rolled over.
743772
#[cfg_attr(
744773
feature = "clap",
745-
arg(long, env, value_name = "PERIOD", requires = "rolling_logs_group")
774+
arg(long, env, value_name = "PERIOD", requires = "file_log")
746775
)]
747-
pub rolling_logs_period: Option<RollingPeriod>,
776+
pub file_log_rotation_period: Option<RotationPeriod>,
748777

749-
/// Enable exporting traces via OTLP.
778+
/// Enable exporting OpenTelemetry traces via OTLP.
750779
#[cfg_attr(feature = "clap", arg(long, env))]
751-
pub otlp_traces: bool,
780+
pub otel_trace_exporter_enabled: bool,
752781

753-
/// Enable exporting logs via OTLP.
782+
/// Enable exporting OpenTelemetry logs via OTLP.
754783
#[cfg_attr(feature = "clap", arg(long, env))]
755-
pub otlp_logs: bool,
784+
pub otel_log_exporter_enabled: bool,
756785
}
757786

758787
/// Supported periods when the log file is rolled over.
759788
#[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
760789
#[derive(Clone, Debug, Default, PartialEq, Eq, strum::Display, strum::EnumString)]
790+
#[strum(serialize_all = "PascalCase")]
761791
#[allow(missing_docs)]
762-
pub enum RollingPeriod {
792+
pub enum RotationPeriod {
763793
Minutely,
764794
Hourly,
765795
Daily,
@@ -768,13 +798,13 @@ pub enum RollingPeriod {
768798
Never,
769799
}
770800

771-
impl From<RollingPeriod> for Rotation {
772-
fn from(value: RollingPeriod) -> Self {
801+
impl From<RotationPeriod> for Rotation {
802+
fn from(value: RotationPeriod) -> Self {
773803
match value {
774-
RollingPeriod::Minutely => Self::MINUTELY,
775-
RollingPeriod::Hourly => Self::HOURLY,
776-
RollingPeriod::Daily => Self::DAILY,
777-
RollingPeriod::Never => Self::NEVER,
804+
RotationPeriod::Minutely => Self::MINUTELY,
805+
RotationPeriod::Hourly => Self::HOURLY,
806+
RotationPeriod::Daily => Self::DAILY,
807+
RotationPeriod::Never => Self::NEVER,
778808
}
779809
}
780810
}
@@ -982,11 +1012,11 @@ mod test {
9821012
#[test]
9831013
fn pre_configured() {
9841014
let tracing = Tracing::pre_configured("test", TelemetryOptions {
985-
no_console_output: false,
986-
rolling_logs: None,
987-
rolling_logs_period: None,
988-
otlp_traces: true,
989-
otlp_logs: false,
1015+
console_log_disabled: false,
1016+
file_log_directory: None,
1017+
file_log_rotation_period: None,
1018+
otel_trace_exporter_enabled: true,
1019+
otel_log_exporter_enabled: false,
9901020
});
9911021

9921022
assert!(tracing.otlp_trace_settings.is_enabled());

0 commit comments

Comments
 (0)