RUM-3470 feat: Head-based sampling for manual distributed tracing

[ncreated]

What and why?

📦 This PR continues the efforts from #1783 and earlier #1772. It adds support to head-based sampling for distributed traces created manually with Tracer API:

• ✅ Distributed trace sent via Tracer API (*HTTPHeadersWriter):

client-ios-app:     [------ network.span -------]
client backend:         [--- backend span ---]

• ✅ Distributed trace sent via Tracer API (*HTTPHeadersWriter) with implicit parent:

client-ios-app:     [------ active.span -------]
client-ios-app:       [---- network.span ----]
client backend:         [-- backend span --]

How?

In head-based sampling mode, headers must be sampled the same as the injected span context (spanContext.isKept). However, this contradicts with existing init(sampleRate:...) constructors. To accommodate this change, a new initializer (init(samplingStrategy: TraceSamplingStrategy)) was added to each headers writer. Additionally, existing constructors have been deprecated to encourage migration. Users should now consciously choose between arbitrary sampling or the new head-based approach:

// in HTTPHeadersWriter:
public init(sampleRate: Float = 20) // 🟨 now: deprecated
public init(samplingStrategy: TraceSamplingStrategy)


// in B3HTTPHeadersWriter:
public init(sampleRate: Float = 20, injectEncoding: InjectEncoding = .single) // 🟨 now: deprecated
public init(samplingStrategy: TraceSamplingStrategy, injectEncoding: InjectEncoding = .single) 

// in W3CHTTPHeadersWriter:
public init(sampleRate: Float = 20, tracestate: [String: String] = [:]) // 🟨 now: deprecated
public init(samplingStrategy: TraceSamplingStrategy, tracestate: [String: String] = [:])

The TraceSamplingStrategy enum enables both the new behavior (.auto) and the previous one (.custom(sampleRate:)):

/// Available strategies for sampling trace propagation headers.
public enum TraceSamplingStrategy {
    /// Trace propagation headers will be sampled same as propagated span.
    ///
    /// Use this option to leverage head-based sampling, where the decision to keep or drop the trace
    /// is determined from the first span of the trace, the head, when the trace is created. With `.auto`
    /// strategy, this decision is propagated through the request context to downstream services.
    case auto
    /// Trace propagation headers will be sampled independently from sampling decision in propagated span.
    ///
    /// Use this option to apply the provided `sampleRate` for determining the decision to keep or drop the trace
    /// in downstream services independently of sampling their parent span.
    case custom(sampleRate: Float)
}

💡 Alternatives Considered

Another option was introducing new types for head-based sampling, but this approach would require solving the RUM-3535: Trace Context injection control issue first. It would simplify things, notably the uniformity of setting trace propagation headers across writers which varies:

• only if "keep" in HTTPHeadersWriter and in B3HTTPHeadersWriter
• "always" in W3CHTTPHeadersWriter

Adopting head-based sampling in existing writers was chosen to avoid this complexity.

Review checklist

• Feature or bugfix MUST have appropriate tests (unit, integration)
• Make sure each commit and the PR mention the Issue number or JIRA reference
• Add CHANGELOG entry for user facing changes

Custom CI job configuration (optional)

• Run unit tests for Core, RUM, Trace, Logs, CR and WVT
• Run unit tests for Session Replay
• Run integration tests
• Run smoke tests
• Run tests for tools/

[datadog-datadog-prod-us1]

Datadog Report

Branch report: ncreated/RUM-3470/head-based-sampling-part2-with-new-init
Commit report: 8ec55a4
Test service: dd-sdk-ios

✅ 0 Failed, 3016 Passed, 0 Skipped, 11m 35.89s Wall Time
🔻 Test Sessions change in coverage: 12 decreased, 2 increased

🔻 Code Coverage Decreases vs Default Branch (12)

This report shows up to 5 code coverage decreases.

• test DatadogRUMTests tvOS 80.66% (-0.37%) - Details
• test DatadogLogsTests tvOS 45.05% (-0.32%) - Details
• test DatadogLogsTests iOS 45.01% (-0.31%) - Details
• test DatadogCoreTests tvOS 79.37% (-0.25%) - Details
• test DatadogCrashReportingTests iOS 27.68% (-0.21%) - Details

[ncreated]

🧹 I'm removing these tests from integration layer. Headers encoding / decoding was moved to DatadogTrace unit tests. This includes adding missing UT coverage for HTTPHeadersWriter.

[ncreated]

blocking/ Note to myself:

• Port this new API to objective-C

[ganeshnj]

Neatly done @ncreated :kudos

[ganeshnj]

Changing the default to auto/head is behavior breaking change. We must make sure this in our changelog.

[ncreated]

@ganeshnj There should be no breaking change here, at least in my best efforts 🙂. Please note that .auto here implies "derive sampling decision (0|1) from injected span context". The injectedSpanContext is sampled with the same sampler that was used before:

let injectedSpanContext = TraceContext(
   // ...
   sampleRate: sampler.samplingRate,
   isKept: sampler.sample()
)

Let me know WDYT or if I'm missing something.

[ganeshnj]

here injected span context is basically span context of active span (Tracer) which we were not considering before while sampling the distributed trace (URLSessionTracking), which could mean more traces depending on the sampling rate defined at Trace level.

[ncreated]

I see. So this regards changes made to TracingURLSessionHandler - RUM handler is backward compatible 👌. I will add a note on this in the consolidation PR (#1794).

[ganeshnj]

💪