What and why?

Currently, when URLSession requests are instrumented by the RUM feature (through the use of the RUM.Configuration.urlSessionTracking configuration option) to generate a RUM Resource, that resource is augmented with a trace and span ID, both generated on the fly, and later used by the backend to synthesize an APM trace span from the RUM resource using those IDs. This is not ideal since that span will be detached from any other trace, breaking the continuity of the generated distributed trace.

This PR links both features: if there is a currently active span for the relevant activity, RUM will use it for augmenting the RUM resource. Specifically:

• The active span's trace ID will be used as the RUM resource trace ID;
• The active span's ID will be used as the RUM resource parent span ID;
• The active span sampling information (priority and decision mechanism) will be used for the RUM resource.
• The RUM resource span ID will still be created on the fly and propagated through the request headers, since any child spans created by the customer's backend tracers and agents need to be children of that ID.

The use of the active span's priority and decision mechanism implies the sampleRate part of the FirstPartyHostsTracing argument of urlSessionTracking will be ignored if there is an active span. As an example:

RUM.enable(
  with: RUM.Configuration(
    applicationID: appID,
    sessionSampleRate: 20,
    (…)
    urlSessionTracking: .init(
      firstPartyHostsTracing: .trace(
          hosts: ["example.com"],
          sampleRate: 10,  // 👈 This is ignored if there is an active span. It's still used otherwise.
          traceControlInjection: .sampled),
        resourceAttributesProvider: nil)
   )
)

As a reminder, even if the active span is not sampled, the RUM resource itself will be sampled if the RUM session is sampled. The only thing the active span sampling controls is if Datadog backend generates the APM trace span out of the RUM resource, or not.

How?

Trace feature initialization adds an instance of ActiveSpanProvider as additional context to the core. This entity contains a provider function that is used to dynamically obtain the active span.

The RUM feature creates an ActiveSpanProviderReceiver and registers it as a feature message receiver. When the context is updated, this receiver obtains the ActiveSpanProvider from the context and stores it. The instance of ActiveSpanProviderReceiver is also placed on the DistributedTracing instance, allowing URLSessionRUMResourcesHandler to finally obtain the active span and properly augment the RUM resource with it.

Notes

• This is an "always on" feature as long as both RUM and Trace are enabled. A configuration option to turn this off was considered, but there is not an obvious use case where the users would want to disable this feature that justifies the added complexity of yet another configuration option.
• The W3C trace context headers have a parent-id key. However, this key expects the RUM resource span ID, not its parent, the active span ID. This is confusing since the other header formats (Datadog and B3) both have explicit fields for the span and parent span IDs, implying the meaning of "parent" ID is different in the W3C case. This, however, makes sense, since the RUM resource span ID will be used as the parent span for any span created in the customers' backends.
• The function that adds an additional context to the core runs asynchronously, so there's a small chance the context was not yet updated when RUM starts instrumenting requests. The probability of this happening is rather low, but this is something that cannot be avoided with the current architecture.

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
• Add Objective-C interface for public APIs - see our guidelines (internal)
• Run make api-surface when adding new APIs