URL

https://opentelemetry.io/docs/languages/go/sampling/

Description

What needs to be changed?

The current documentation for Go sampling only covers the built-in samplers. It lacks guidance on how to create a custom sampler. More importantly, it doesn't explain how a custom sampler's implementation can affect the propagation of tracestate and baggage between parent and child spans. An incorrectly implemented custom sampler can lead to dropped or modified tracestate and baggage, causing context propagation issues.

The documentation should be updated to include:

• A guide on how to create a custom sampler in Go by implementing the Sampler interface.
• An explanation of how the SamplingResult field should be handled to ensure correct propagation.
• A best-practice example of a custom sampler that correctly handles tracestate and preserves baggage.

Additional context:

When creating a custom sampler, developers need to be aware that they are responsible for preserving the context. If a custom sampler returns a SamplingResult without the original Tracestate from the parent, it can break the context propagation. This is not obvious from the current documentation. This is a critical detail for anyone building custom sampling logic in a distributed system that relies on tracestate or baggage for passing application-specific data. Adding this information to the documentation would help prevent common pitfalls and ensure more robust tracing implementations.

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}