Fix nullable annotations on Activity duck types (#8038)

## Summary of changes

Fix incorrect nullable annotations on `Activity` duck types

## Reason for change

While working on other performance things, noticed that the nullable
annotations often declared non-nullability when they actually could be
null.

A particularly confusing part are the `TraceId` and `SpanId` values in
`IW3CActivity`. These were marked non-nullable because when you call
`Activity.Start()` then these will always be non-null, but _only_ if
you're using W3C IDs. If you're using hierarchical IDs ([the default in
<.NET
5](https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/5.0/default-activityidformat-changed))
then these values _will_ be null.

As a side note, I suspect this explains the "we saw errors about these
being null in error tracking but don't understand why" scenarios 😄

Also, I think we should rename `IW3CActivity` to `IActivity3` instead.
W3C _implies_ that it's a W3C activity, but that's not necessarily the
case, and is essentially the source of the above confusion I think.
`IActivity3` would then be consistently named with `IActivity5` and
`IActivity6` we also currently have.

## Implementation details

Add nullable annotations to values that _can_ be null, and fix the
fallout (mostly in `ActivityKey`)

## Test coverage

Covered by existing tests sufficiently I think

## Other details

https://datadoghq.atlassian.net/browse/LANGPLAT-915

Part of a stack working to improve OTel performance

- #8036
- #8037 👈
- #8038
- #8039
- #8040
- #8041
- #8042

Author: andrewlock

tracer/src/Datadog.Trace/Activity/DuckTypes/IActivity.cs

@@ -13,10 +13,13 @@ namespace Datadog.Trace.Activity.DuckTypes
 {
     internal interface IActivity : IDuckType
     {
-        // The corresponding property on the Activity object is nullable,
-        // but we are guaranteed that the value will not be null once the Activity is started.
-        // Since we are only accessing the Activity after it has started, we can treat the value
-        // as never having a null value.
+        /// <summary>
+        /// Gets an ID for the activity. If the Activity is using hierarchical IDs, the Id has a hierarchical structure:
+        /// '|root-id.id1_id2.id3_' and is generated when Start() is called by appending suffix to Parent.Id
+        /// or ParentId; Activity has no Id until it started, but as we only see started IDs, this will always be non null.
+        /// </summary>
+        /// <remarks>NOTE: this property allocates when using W3C activities, and so should generally not be called
+        /// unless you know that you're not using W3C activities (because <see cref="IW3CActivity.SpanId"/> is null</remarks>
         string Id { get; }
 
         string? ParentId { get; }
@@ -35,9 +38,9 @@ internal interface IActivity : IDuckType
 
         DateTime StartTimeUtc { get; }
 
-        IEnumerable<KeyValuePair<string, string>> Baggage { get; }
+        IEnumerable<KeyValuePair<string, string?>> Baggage { get; }
 
-        IEnumerable<KeyValuePair<string, string>> Tags { get; }
+        IEnumerable<KeyValuePair<string, string?>> Tags { get; }
 
         object AddBaggage(string key, string value);
 

tracer/src/Datadog.Trace/Activity/DuckTypes/IActivity5.cs

@@ -18,7 +18,7 @@ internal interface IActivity5 : IW3CActivity
 
         ActivityKind Kind { get; }
 
-        IEnumerable<KeyValuePair<string, object>> TagObjects { get; }
+        IEnumerable<KeyValuePair<string, object?>> TagObjects { get; }
 
         ActivitySource Source { get; }
 

tracer/src/Datadog.Trace/Activity/DuckTypes/IW3CActivity.cs

@@ -11,11 +11,14 @@ namespace Datadog.Trace.Activity.DuckTypes
 {
     internal interface IW3CActivity : IActivity
     {
+        // Note that TraceId and SpanId will not be null when using W3C IDs, but they
+        // _Can_ be nullable when using Hierarchical IDs. Also note that IW3CActivity
+        // could be using _either_ type of ID
         [DuckField(Name = "_traceId")]
-        string TraceId { get; set; }
+        string? TraceId { get; set; }
 
         [DuckField(Name = "_spanId")]
-        string SpanId { get; set; }
+        string? SpanId { get; set; }
 
         [DuckField(Name = "_parentSpanId")]
         string ParentSpanId { get; set; }

tracer/src/Datadog.Trace/Activity/Handlers/AzureServiceBusActivityHandler.cs

@@ -46,15 +46,11 @@ public void ActivityStopped<T>(string sourceName, T activity)
                 // then we can retrieve the active message object using our mapping. With access to the message
                 // object, we can accurately calculate the payload size for the DataStreamsCheckpoint
 
-                ActivityKey key;
-                if (activity is IW3CActivity w3cActivity)
+                ActivityKey key = activity switch
                 {
-                    key = new(w3cActivity.TraceId, w3cActivity.SpanId);
-                }
-                else
-                {
-                    key = new ActivityKey(activity.Id);
-                }
+                    IW3CActivity { TraceId: not null, SpanId: not null } w3cActivity => new(w3cActivity.TraceId, w3cActivity.SpanId),
+                    _ => new(activity.Id)
+                };
 
                 if (key.IsValid() && ActivityHandlerCommon.ActivityMappingById.TryRemove(key, out ActivityMapping activityMapping)
                     && activityMapping.Scope?.Span is Span span)

tracer/src/Datadog.Trace/Activity/Handlers/QuartzActivityHandler.cs

@@ -47,7 +47,7 @@ public void ActivityStopped<T>(string sourceName, T activity)
             // Find the span and update it before the common handler processes it
             ActivityKey key = activity switch
             {
-                IW3CActivity w3cActivity => new(w3cActivity.TraceId, w3cActivity.SpanId),
+                IW3CActivity { TraceId: not null, SpanId: not null } w3cActivity => new(w3cActivity.TraceId, w3cActivity.SpanId),
                 _ => new(activity.Id)
             };