[SDK] Implement ComposableSampler

[marcalff]

ComposableSampler are a recent addition in the specifications.

Implement support in the SDK.

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#compositesampler

[github-actions]

This issue is available for anyone to work on. Make sure to reference this issue in your pull request.
✨ Thank you for your contribution! ✨

[mateenali66]

interested in picking this up, quick scoping question first.

#3966 adds the config-side DTOs under sdk/configuration/ and wires sdk_builder.cc to instantiate composable variants. reading #4028 as the trace-side piece: actual sampler classes under sdk/src/trace/samplers/ (ComposableAlwaysOn/Off, ComposableParentThreshold, ComposableProbability, ComposableRuleBased) plus the composition semantics from the spec. does that split match what you had in mind?

also: one PR covering all variants + composition, or split per variant? whichever is easier to review.

[marcalff]

@mateenali66

interested in picking this up, quick scoping question first.

Thanks for volunteering.

#3966 adds the config-side DTOs under sdk/configuration/ and wires sdk_builder.cc to instantiate composable variants. reading #4028 as the trace-side piece: actual sampler classes under sdk/src/trace/samplers/ (ComposableAlwaysOn/Off, ComposableParentThreshold, ComposableProbability, ComposableRuleBased) plus the composition semantics from the spec. does that split match what you had in mind?

Yes.

#3966 is now merged, so the next part is to implement the SDK logic itself, under sdk/src/trace/samplers/.

also: one PR covering all variants + composition, or split per variant? whichever is easier to review.

One PR is more practical.

Expect slow/no replies next week, but I will be available for review/guidance after that.

[mateenali66]

starting to sketch this. before committing to the rest of the variants and tests, wanted to float the interface shapes so you can redline anything early.

proposed types

struct SamplingIntent
{
  uint64_t threshold_value = 0;   // 56-bit value in low bits; R >= T keeps
  bool has_threshold       = false;  // false = drop unconditionally
  bool threshold_reliable  = false;  // true = write "ot"/"th:" back

  AttributesProvider  attributes_provider{};   // invoked only on keep
  TraceStateProvider  trace_state_provider{};  // applied before CompositeSampler writes "th:"
};

class ComposableSampler
{
public:
  virtual SamplingIntent GetSamplingIntent(
      const trace::SpanContext &parent_context,
      trace::TraceId trace_id,
      nostd::string_view name,
      trace::SpanKind span_kind,
      const common::KeyValueIterable &attributes,
      const trace::SpanContextKeyValueIterable &links) noexcept = 0;

  virtual nostd::string_view GetDescription() const noexcept = 0;
};

class CompositeSampler : public Sampler {
  // owns the SamplingIntent -> SamplingResult translation
  // owns the "ot" tracestate write-back ("th:", "rv:")
};

open questions

1. threshold representation. going with uint64_t threshold_value + bool has_threshold. considered std::optional<uint64_t> but the rest of the SDK avoids <optional> for ABI reasons. OK?
2. tracestate "ot" codec. putting the parse/serialize helpers in a private sdk/src/trace/samplers/ot_tracestate.cc helper. not exporting them. alternative is a public util under sdk/common/ if you anticipate reuse from non-sampler code. preference?
3. ComposableParentThreshold root param. the spec says a root delegate is required; I'll pass it as std::shared_ptr<ComposableSampler> to allow the caller to share it. any issue with shared vs unique ownership?
4. ComposableRuleBased rules. modeling each rule as { Predicate(attrs, name, kind) -> bool; std::shared_ptr<ComposableSampler> sampler; }. predicate type is std::function<bool(...)>. good with std::function, or would you rather have an abstract Predicate base class to avoid std::function heap allocs on the hot path?
5. factory pattern. following the existing *Factory::Create() convention for each of the 5 variants + CompositeSamplerFactory. anything you'd rather I do differently?
6. sdk_builder.cc. the FIXME-SDKs in [CONFIGURATION] File configuration - composable samplers #3966 currently fall back to AlwaysOn/TraceIdRatioBased. once the real classes land, I'll wrap them in CompositeSampler there. or do you want sdk_builder to expose both ComposableSampler-only and wrapped-Sampler paths?

the four header files (base, composite, always_on, always_off) exist locally as a starting point. I'll push the rest of the variants once 1-4 above are settled. no rush, happy to wait until you are back in the loop next week.