Skip to content

Document default values of telemetry settings - #316

Open
Mattbusel wants to merge 1 commit into
cloudflare:mainfrom
Mattbusel:docs/telemetry-setting-defaults
Open

Mattbusel wants to merge 1 commit into
cloudflare:mainfrom
Mattbusel:docs/telemetry-setting-defaults

Conversation

@Mattbusel

Copy link
Copy Markdown

Closes #41.

Adds the default of each telemetry setting to its doc comment where the docs did not already state it, in the spelling the YAML config uses (terminal, text, INFO, metric_prefix, jaeger_thrift_udp, active). Settings that already said their default (max_queue_size, the OTLP and Jaeger output settings, sample_interval, track_all_spans) are left as they were, apart from rewording the Jaeger num_tasks default to match its neighbours. Each value comes from the field's #[serde(default = ...)] function or the type's Default, for example TelemetryServerSettings defaults to enabled on 127.0.0.1:0, tracing defaults to enabled, and LivenessTrackingSettings::default() is disabled outside this crate's own tests.

One default is worth calling out in the text: max_events_per_second defaults to 0, and both rate limiters skip the limit when it is 0 (NonZeroU32::new), so enabled: true alone does not limit anything.

Since these doc comments are also what -g writes into generated config files, the defaults show up there too. I checked that with cargo run --example http_server -- -g. The checked-in example_conf.yaml is hand-tuned (tracing disabled, OTLP output), so I did not regenerate it.

Also fixes three stale references:

  • Under TracesOutput::OpenTelemetryGrpc, the link definition was labelled [Jaeger Thrift (UDP)], so [Open Telemetry] did not render as a link.
  • reporter_bind_addr said it must match the address family of jaeger_tracing_server_addr, the pre-4.0 field name. It now says server_addr.
  • The bootstrap error for mismatched address families named jaeger_tracing_server_addr and jaeger_reporter_bind_addr, which do not exist in 4.x configs. It now names server_addr and reporter_bind_addr.

Checked: rustfmt --check --edition 2024 on all files, and cargo +nightly doc --lib --no-deps --all-features --document-private-items with the CI RUSTDOCFLAGS (-Dwarnings, foundations_docsrs) passes.

Prepared with AI assistance (Claude); the checks above were run locally before opening.

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 cloudflare#41

Assisted-by: Claude:claude-opus-5-5
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document default values for telemetry settings

1 participant