RUMM-2924 Create DatadogTrace API for 2.x

[ncreated]

What and why?

📦 This PR extracts DatadogTrace public API for 2.0.0.

The new API for tracing will consist of 3 main interfaces:

// Configuration:
let config: Trace.Configuration

// Feature:
Trace.enable(with: config)

// Tracer API:
Tracer.shared() -> OTTracer

@maxep please note that I'm not introducing TracerProtocol like we do for RUM monitor and Logger. Unlike these two, our tracer conforms to external Open Tracing standard and hence IMO we should using existing OTTracer interface. Even though OT is deprecated and it is just a conventional conformance, long term we will rather switch to OTel and not our custom interface.

How?

Only mandatory updates and following convention:

• removal of V1 Trace configuration from Datadog;
• addition of V2 Trace.Configuration in DatadogTrace;
• re-creation of V2 DDTraceConfiguration in DatadogObjc;
• updates in DatadogTests where we still carry on Tracer tests;
• updates to Example app to use V2 Trace API;
• updates to IntegrationTests project to use V2 Trace API
• updates to smoke tests
• updates to Carthage setup in pbxproj

Distributed Tracing API

Because URLSession instrumentation can be enabled in both RUM and Trace configuration, I kept the same convention in its setup (aligned with #1321).

By default, no URLSession instrumentation is installed (distributed tracing is disabled):

let config = Trace.Configuration()
XCTAssertNil(config.urlSessionTracking)

To enable distributed tracing with x-datadog-* headers:

config.urlSessionTracking = .init(
   firstPartyHostsTracing: .trace(hosts: ["example.com"]) // 20% sample rate by default
)
config.urlSessionTracking = .init(
   firstPartyHostsTracing: .trace(hosts: ["example.com"], sampleRate: 100) // custom sample rate
)

To enable distributed tracing with custom headers:

config.urlSessionTracking = .init(
   firstPartyHostsTracing: .traceWithHeaders(
      hostsWithHeaders: ["example.com": [.b3, .datadog]] // 20% sample rate by default
   )
)
config.urlSessionTracking = .init(
   firstPartyHostsTracing: .traceWithHeaders(
      hostsWithHeaders: ["example.com": [.b3, .datadog]],
      sampleRate: 100 // custom sample rate
   )
)

❗ Note, that network instrumentation in tracing only works for first party requests. Requests sent to 3rd party URLs won't be traced: no span and no headers injection. Nothing new, just leaving it for clarity.

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
• Run integration tests
• Run smoke tests

[datadog-datadog-prod-us1]

Datadog Report

Branch report: ncreated/RUMM-2924/traces-api-v2
Commit report: 17f12c3

✅ dd-sdk-ios: 0 Failed, 0 New Flaky, 156 Passed, 0 Skipped, 15m 11.77s Wall Time

[ncreated]

Leaving it not renamed, because I feel we lack solid convention for such things. I can rename it to anything (<whatever>Tracer) but I wish we can make up some no-brainer pattern to follow - likely on next iOS Dev Chat.

[maxep]

Perfect 👌

I've left one non-blocking question but it's good to go IMO!

[maxep]

I wonder if shouldn't combine this one and RUM.Configuration.URLSessionTracking into a single config struct defined in DatadogInternal 🤔

Not a change request but I would like your opinion on this?

[ncreated]

I was thinking about this 👌, but IMO this wouldn't be correct nor user-friendly.

First, there is a slight but key difference in both:

// DatadogRUM:
public struct URLSessionTracking {
    public var firstPartyHostsTracing: FirstPartyHostsTracing? // <-- ❗️ optional
    public var resourceAttributesProvider: RUM.ResourceAttributesProvider?
}

// DatadogTrace:
public struct URLSessionTracking {
    public var firstPartyHostsTracing: FirstPartyHostsTracing // <-- ❗️ non-optional
}

Not only RUM takes resourceAttributesProvider, but also optionality of firstPartyHostsTracing is different. This comes from the fact that:

• If URLSession is instrumented by RUM, it tracks all requests as RUM resource. Additionally it will inject tracing headers to first-party requests, hence we ask for their definition optionaly.
• If URLSession is instrumented by Trace, it doesn't track all requests (ref.: RUMM-696 Stop sending tracing Span for RUM Resources #314). It only intercepts first-party requests and injects tracing headers. Hence, it doesn't make sense to have URLSessionTracking without definition of hosts.

Next, because of that difference ☝️ , it could be hard to come up with a single definition of URLSessionTracking that works for both products and includes product-agnostic explanation in API comment.

Last, this ☝️ is the difference we have today. It is easy to imagine this drifting even more away (e.g. distinguishing the default sampleRate value in FirstPartyHostsTracing enum of both products or adding more header types, only in RUM). Consider the fact that RUM and APM are separate DD products with distinct infrastructure which might translate into separate constraints.

For all that reasons, I think it is safer to duplicate this definition than assume wrong abstraction. To help users with adopting this, I made sure that both URLSessionTracking and FirstPartyHostsTracing APIs stay close to each other in both products.

How does it all sound @maxep ?

[ncreated]

Also, keep in mind that there is no practical use case of "sharing config definition" by the user. RUM offers a superset of distributed tracing - if you enable automatic RUM resources with urlSessionTracking, no real point of enabling APM network tracing as RUM will do distributed tracing for you.

[maxep]

It all makes sense, thanks for the clarification 🙏