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,