From 8ef724eebc9d9e7e093bc09322f3057a3a1faa95 Mon Sep 17 00:00:00 2001 From: Matthew Charles Busel Date: Tue, 17 Nov 2026 18:52:32 -0500 Subject: [PATCH] Document default values of telemetry settings Add the default of each telemetry setting to its doc comment, in the spelling the YAML config uses, where the docs did not already state it. The rustdoc of these structs is also what `--generate` writes into generated config files, so the defaults show up there too. Also fix two stale references: the Open Telemetry link definition under TracesOutput was labelled "Jaeger Thrift (UDP)", so the link did not render, and reporter_bind_addr's docs and its address family error still named the pre-4.0 fields `jaeger_tracing_server_addr` and `jaeger_reporter_bind_addr`. Closes #41 Assisted-by: Claude:claude-opus-5-5 --- foundations/src/telemetry/settings/logging.rs | 20 +++++++++++-- .../src/telemetry/settings/memory_profiler.rs | 4 ++- foundations/src/telemetry/settings/metrics.rs | 4 +++ .../src/telemetry/settings/rate_limit.rs | 8 +++-- foundations/src/telemetry/settings/server.rs | 6 +++- foundations/src/telemetry/settings/tracing.rs | 29 ++++++++++++++----- .../tracing/output_jaeger_thrift_udp.rs | 4 +-- 7 files changed, 58 insertions(+), 17 deletions(-) diff --git a/foundations/src/telemetry/settings/logging.rs b/foundations/src/telemetry/settings/logging.rs index 0e1a0ea4..01e8fa87 100644 --- a/foundations/src/telemetry/settings/logging.rs +++ b/foundations/src/telemetry/settings/logging.rs @@ -25,18 +25,26 @@ feature_use!(cfg(feature = "settings"), { #[cfg_attr(not(feature = "settings"), derive(Clone, Default, Debug))] pub struct LoggingSettings { /// Specifies log output. + /// + /// Defaults to `terminal`. pub output: LogOutput, /// The format to use for log messages. + /// + /// Defaults to `text`. pub format: LogFormat, /// Set the logging verbosity level. + /// + /// Defaults to `INFO`. pub verbosity: LogVerbosity, /// A list of field keys to redact when emitting logs. /// /// This might be useful to hide certain fields in production logs as they may /// contain sensitive information, but allow them in testing environment. + /// + /// Defaults to an empty list. pub redact_keys: Vec, /// Whether to ignore I/O errors from built-in log outputs. @@ -44,12 +52,18 @@ pub struct LoggingSettings { /// By default, I/O errors from terminal, stderr, and file outputs are treated /// as fatal logging failures. Enabling this setting allows services to keep /// running if a log sink returns an error such as [`std::io::ErrorKind::BrokenPipe`]. + /// + /// Defaults to `false`. pub ignore_io_errors: bool, - /// Settings for rate limiting emission of log events + /// Settings for rate limiting emission of log events. + /// + /// Rate limiting is disabled by default. pub rate_limit: RateLimitingSettings, /// Configure log volume metrics. + /// + /// Log volume metrics are disabled by default. pub log_volume_metrics: LogVolumeMetricSettings, } @@ -194,6 +208,8 @@ impl From for slog::Level { #[cfg_attr(feature = "settings", settings(crate_path = "crate"))] #[cfg_attr(not(feature = "settings"), derive(Clone, Debug, Default))] pub struct LogVolumeMetricSettings { - /// Whether to enable log volume metrics + /// Whether to enable log volume metrics. + /// + /// Defaults to `false`. pub enabled: bool, } diff --git a/foundations/src/telemetry/settings/memory_profiler.rs b/foundations/src/telemetry/settings/memory_profiler.rs index b7cae788..6f2dafad 100644 --- a/foundations/src/telemetry/settings/memory_profiler.rs +++ b/foundations/src/telemetry/settings/memory_profiler.rs @@ -5,7 +5,9 @@ use crate::settings::settings; #[cfg_attr(feature = "settings", settings(crate_path = "crate"))] #[cfg_attr(not(feature = "settings"), derive(Clone, Debug, serde::Deserialize))] pub struct MemoryProfilerSettings { - /// Enables memory profiling + /// Enables memory profiling. + /// + /// Defaults to `false`. pub enabled: bool, /// Value between `0` and `64` which specifies the number of bytes of diff --git a/foundations/src/telemetry/settings/metrics.rs b/foundations/src/telemetry/settings/metrics.rs index 2fca35f6..c2a42dc6 100644 --- a/foundations/src/telemetry/settings/metrics.rs +++ b/foundations/src/telemetry/settings/metrics.rs @@ -7,9 +7,13 @@ use crate::settings::settings; pub struct MetricsSettings { /// How the metrics service identifier defined in `ServiceInfo` is used /// for this service. + /// + /// Defaults to `metric_prefix`. pub service_name_format: ServiceNameFormat, /// Whether to report optional metrics in the telemetry server. + /// + /// Defaults to `false`. pub report_optional: bool, } diff --git a/foundations/src/telemetry/settings/rate_limit.rs b/foundations/src/telemetry/settings/rate_limit.rs index 2cdc245e..f1a0347d 100644 --- a/foundations/src/telemetry/settings/rate_limit.rs +++ b/foundations/src/telemetry/settings/rate_limit.rs @@ -8,9 +8,13 @@ use crate::settings::settings; derive(Clone, Debug, Default, serde::Deserialize) )] pub struct RateLimitingSettings { - /// Whether to enable rate limiting of events + /// Whether to enable rate limiting of events. + /// + /// Defaults to `false`. pub enabled: bool, - /// Maximum number of events that can be emitted per second + /// Maximum number of events that can be emitted per second. + /// + /// Defaults to `0`. A value of `0` applies no limit, even when `enabled` is `true`. pub max_events_per_second: u32, } diff --git a/foundations/src/telemetry/settings/server.rs b/foundations/src/telemetry/settings/server.rs index 203521d1..1af5677a 100644 --- a/foundations/src/telemetry/settings/server.rs +++ b/foundations/src/telemetry/settings/server.rs @@ -6,11 +6,15 @@ use crate::settings::settings; #[cfg_attr(feature = "settings", settings(crate_path = "crate"))] #[cfg_attr(not(feature = "settings"), derive(Clone, Debug, serde::Deserialize))] pub struct TelemetryServerSettings { - /// Enables telemetry server + /// Enables telemetry server. + /// + /// Defaults to `true`. #[serde(default = "TelemetryServerSettings::default_enabled")] pub enabled: bool, /// Telemetry server address. + /// + /// Defaults to `127.0.0.1:0`, a port the OS picks on the loopback interface. #[serde(default = "TelemetryServerSettings::default_addr")] pub addr: ListenAddr, } diff --git a/foundations/src/telemetry/settings/tracing.rs b/foundations/src/telemetry/settings/tracing.rs index 21b04d9b..ddd2e4d5 100644 --- a/foundations/src/telemetry/settings/tracing.rs +++ b/foundations/src/telemetry/settings/tracing.rs @@ -19,6 +19,8 @@ use std::net::SocketAddr; #[cfg_attr(not(feature = "settings"), derive(Clone, Debug, serde::Deserialize))] pub struct TracingSettings { /// Enables tracing. + /// + /// Defaults to `true`. #[serde(default = "TracingSettings::default_enabled")] pub enabled: bool, @@ -32,18 +34,23 @@ pub struct TracingSettings { pub max_queue_size: Option, /// The output for the collected traces. + /// + /// Defaults to `jaeger_thrift_udp` with its default settings. pub output: TracesOutput, /// The strategy used to sample traces. + /// + /// Defaults to `active` sampling with a sampling ratio of `1.0` and no rate limit. pub sampling_strategy: SamplingStrategy, - /// Enable liveness tracking of all generated spans. Even if the spans are - /// unsampled. This can be useful for debugging potential hangs caused by - /// some objects remaining in memory. The default value is false, meaning - /// only sampled spans are tracked. + /// Liveness tracking of generated spans. This can be useful for debugging + /// potential hangs caused by some objects remaining in memory. /// /// To get a json dump of the currently active spans, query the telemetry /// server's route at `/debug/traces`. + /// + /// Disabled by default. When enabled, only sampled spans are tracked unless + /// `track_all_spans` is set. pub liveness_tracking: LivenessTrackingSettings, } @@ -85,7 +92,7 @@ pub enum TracesOutput { /// Sends traces to the collector in the [Open Telemetry] format over [gRPC]. /// - /// [Jaeger Thrift (UDP)]: https://opentelemetry.io/ + /// [Open Telemetry]: https://opentelemetry.io/ /// [gRPC]: https://grpc.io/ #[cfg(feature = "telemetry-otlp-grpc")] OpenTelemetryGrpc(OpenTelemetryGrpcOutputSettings), @@ -115,14 +122,14 @@ pub struct JaegerThriftUdpOutputSettings { /// By default, the reporter API is only exposed on the loopback /// interface. This won't work in environments where the /// Jaeger agent is on another host (for example, Docker). - /// Must have the same address family as `jaeger_tracing_server_addr`. + /// Must have the same address family as `server_addr`. pub reporter_bind_addr: Option, /// Number of concurrent tasks to spawn for output. /// /// A higher number means more spans can be collected in parallel in a /// multi-threaded runtime. All tasks share a UDP socket for sending datagrams. - /// The default is 1 task. + /// Defaults to `1`. #[serde(default = "JaegerThriftUdpOutputSettings::default_num_tasks")] pub num_tasks: usize, @@ -176,10 +183,14 @@ pub struct ActiveSamplingSettings { /// /// This can be any fractional value between `0.0` and `1.0`. /// Where `1.0` means "sample everything", and `0.0` means "don't sample anything". + /// + /// Defaults to `1.0`. #[serde(default = "ActiveSamplingSettings::default_sampling_ratio")] pub sampling_ratio: f64, - /// Settings for rate limiting emission of traces + /// Settings for rate limiting emission of traces. + /// + /// Rate limiting is disabled by default. pub rate_limit: RateLimitingSettings, } @@ -241,6 +252,8 @@ impl Default for SamplingStrategy { #[cfg_attr(not(feature = "settings"), derive(Clone, Debug, serde::Deserialize))] pub struct LivenessTrackingSettings { /// Enables liveness tracking. + /// + /// Defaults to `false`. pub enabled: bool, /// Enable liveness tracking of all generated spans. Even if the spans are /// unsampled. This can be useful for debugging potential hangs caused by diff --git a/foundations/src/telemetry/tracing/output_jaeger_thrift_udp.rs b/foundations/src/telemetry/tracing/output_jaeger_thrift_udp.rs index 2a184387..cdfcc81c 100644 --- a/foundations/src/telemetry/tracing/output_jaeger_thrift_udp.rs +++ b/foundations/src/telemetry/tracing/output_jaeger_thrift_udp.rs @@ -54,9 +54,7 @@ fn get_reporter_bind_addr(settings: &JaegerThriftUdpOutputSettings) -> Bootstrap if settings.server_addr.is_ipv6() == addr.is_ipv6() { addr.into() } else { - bail!( - "`jaeger_tracing_server_addr` and `jaeger_reporter_bind_addr` must have the same address family" - ); + bail!("`server_addr` and `reporter_bind_addr` must have the same address family"); } } // caused by https://github.com/sile/rustracing_jaeger/blob/bc7d03f2f6ac6bc0269542089c8907279706ecb7/src/reporter.rs#L34,