open-telemetry
[Page feedback]: Flesh out usage of combining sampling strategies
URL
https://opentelemetry.io/docs/languages/go/sampling/
Description
As-written, this page currently explains that TracerProviders can be set up with Samplers and some useful Sampler primitives are already supplied (AlwaysSample, NeverSample, TraceIDRatioBased and ParentBased — these cover most sampling policies, so it's great to have them available out-of-the-box!)
Pedagogically, I think the page would be helped by a reference to the concepts of head-based and tail-based sampling.
More concretely, I find this phrasing unhelpful:
By default, the tracer provider uses a ParentBased sampler with the AlwaysSample sampler.
When in a production environment, consider using the ParentBased sampler with the TraceIDRatioBased sampler.
It's good to know samplers can be combined, but it doesn't explain how they should be combined, and I don't personally find it self-explanatory from the example which sets up a TracerProvider that uses a withSampler that only uses one of the four basic samplers. If you can use two samplers together, what's the way to do that?
While we're at it it would be nice if a corresponding page with examples for the Python SDK existed (that's what I'm really using, but I didn't see a Sampling page in the Python section sidebar)
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.
While we're at it it would be nice if a corresponding page with examples for the Python SDK existed (that's what I'm really using, but I didn't see a Sampling page in the Python section sidebar)
Oh, regarding this point, I found what I wanted here, pretty easily too.
I just got a bit confused since the two information sources are hosted in separate places...
Hi @sinback, thanks a lot for the detailed feedback! 🙌🏼
You've raised some really good points here — I see we have a few opportunities for improvement, so let me break them down.
Concepts reference: Under the Sampling section in the Concepts page, we already describe head- and tail-based sampling. We could link to that page directly from the Go docs, or even bring a short summary and examples showing how those concepts could be applied in Go.
Combining samplers: I agree that the current explanation doesn't cover how multiple samplers can be combined or what the expected outcome is. Adding a few short, practical examples would definitely make this section more complete.
Mentioning @open-telemetry/go-approvers for an opinion here.
You also mentioned the separate information sources for the Python docs. This is something we've seen across multiple technologies in the project, and we've been tracking those cases in the meta issue #833. We might want to revisit this as part of the ongoing effort to consolidate non-API docs under opentelemetry.io, so we can ensure the consistency and improve discoverability across all SDKs.
@open-telemetry/docs-triagers WDYT?
Rather than have one sampling doc in each SDK (that'll be the same everywhere), should there be a global one that SDK docs can link to?
+1 to dmathieu's suggestion :)
Yeah, regarding the awkwardness of switching between centralized/spec- or concept-oriented docs and specific language docs, it would be really great if the sdk docs focused on in-code-level documentation (so for Python, the docstrings and stuff, which the readthedocs docs already do 👍🏻), but they had links at the top of sections to centralized/spec-oriented stuff. It can be really helpful to refer to both but it adds a little cognitive overload for me to go hunting and flipping in between the two, especially because some of the centralized docs are tailored towards different languages (not always directly in line with the generated and generally "more official" docs for each language), and some are tailored towards the overarching architectural concepts. So yeah organizationally it's a bit haphazard for new learners like me.
I think having a central document is the way to go, I suspect that the declarative configuration is going to help a lot with that, so maybe we need to revisit that in general with the "configuration" section and have some more parts here and there. It's still not stable, in the mean time I am open to update the concept page around sampling with some language-agnostic best practices and notes and pointers to the languages
So what I think I'd personally like to see is:
- Adjust each of the pages to emphasize that this is to configure head sampling at the SDK level, and link to the general sampling page that defines this term
- Use environment variables for configuration and code-based config as an alternative
- Explain that head samplers can be combined
