Skip to content

Document the sw8 Sample value convention and the agent sampling policy - #14204

Merged
wu-sheng merged 1 commit into
masterfrom
doc-sw8-sample-flag
Nov 7, 2026
Merged

wu-sheng merged 1 commit into
masterfrom
doc-sw8-sample-flag

Conversation

@wu-sheng

@wu-sheng wu-sheng commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

Summary

Document how the SkyWalking agents use the sw8 Sample value, in docs/en/api/x-process-propagation-headers-v3.md.

  • SkyWalking builds complete metrics and topology from the reported traces, so agents commonly sample 100%. Storage is reduced instead by server-side trace sampling, which keeps the metrics and topology. So the Sample value, designed at the beginning of the protocol, is not used in practice.
  • By convention, the agents always write 1 and don't use the value to decide whether to trace. I checked Java, Go, Python, Node.js, Rust, nginx-lua, and client-js.
  • When an agent samples, the decision should be made once, by the service that starts the trace. An agent that receives a valid sw8 header should keep that decision instead of applying its own sampling rate. Ignore rules, a disconnected backend, and a full buffer still apply.
  • Rename the "Sample values:" label to "Example value:", which read as if it were about the Sample field.

This came up in #14201, where the Go agent re-sampled propagated traces. The Go agent fix is apache/skywalking-go#264, and its agent.sampler doc links to the new #sampling anchor here.

Note: the Python agent's sampler (SW_SAMPLE_N_PER_3_SECS, off by default) still runs before the incoming header is considered, so it doesn't follow the expected behavior yet.

SkyWalking builds complete metrics and topology from the reported
traces, so agents commonly sample 100%, and storage is reduced by
server-side trace sampling instead. The Sample value, designed at the
beginning of the protocol, is therefore not used in practice: the
agents always write 1 and don't use it to decide whether to trace.

Describe this in the sw8 protocol doc, and state that an agent that
receives a valid sw8 header should keep the upstream sampling decision
instead of applying its own sampling rate. Rename the "Sample values:"
label to "Example value:", which read as if it were about the Sample
field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@wu-sheng
wu-sheng merged commit 287b24f into master Nov 7, 2026
17 checks passed
@wu-sheng
wu-sheng deleted the doc-sw8-sample-flag branch November 7, 2026 10:38
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.

2 participants