From 74fc70e8eb12b075833281e2b82c3940bd9b8813 Mon Sep 17 00:00:00 2001
From: Cijo Thomas <cijo.thomas@gmail.com>
Date: Tue, 12 Nov 2024 22:08:12 -0800
Subject: [PATCH] [docs] Document links maybe added after Activity creation
 (#5972)

---
 src/OpenTelemetry.Api/README.md               | 27 +++++++++++------
 .../Trace/TracerProviderSdkTest.cs            | 29 +++++++++++++++++++
 2 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/src/OpenTelemetry.Api/README.md b/src/OpenTelemetry.Api/README.md
index db0471e1774..09978db05a4 100644
--- a/src/OpenTelemetry.Api/README.md
+++ b/src/OpenTelemetry.Api/README.md
@@ -332,11 +332,13 @@ chose not to sample this activity.
 
 4. Activity Links
 
-   Apart from the parent-child relation, activities can be linked using
-   `ActivityLinks` which represent the OpenTelemetry
-   [Links](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#links-between-spans).
-   The linked activities must be provided during the creation time, as shown
-   below.
+   In addition to parent-child relationships, activities can also be linked
+   using `ActivityLinks`, which represent
+   [Links](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#links-between-spans)
+   in OpenTelemetry. Providing activity links during creation is recommended, as
+   this allows samplers to consider them when deciding whether to sample an
+   activity. However, starting with `System.Diagnostics.DiagnosticSource` 9.0.0,
+   links can also be added after an activity is created.
 
     ```csharp
     var activityLinks = new List<ActivityLink>();
@@ -359,12 +361,19 @@ chose not to sample this activity.
         ActivityKind.Server,
         default(ActivityContext),
         initialTags,
-        activityLinks);
+        activityLinks); // links provided at creation time.
+
+    // One may add links after activity is created too.
+    var linkedContext3 = new ActivityContext(
+        ActivityTraceId.CreateFromString("01260a70a81e1fa3ad5a8acfeaa0f711"),
+        ActivitySpanId.CreateFromString("34739aa9e2239da1"),
+        ActivityTraceFlags.None);
+    activity?.AddLink(linkedContext3);
     ```
 
-    Note that `Activity` above is created with `default(ActivityContext)`
-    parent, which makes it child of implicit `Activity.Current` or orphan if
-    there is no `Current`.
+   Note that `Activity` above is created with `default(ActivityContext)`
+   parent, which makes it child of implicit `Activity.Current` or orphan if
+   there is no `Current`.
 
 ### Adding Events
 
diff --git a/test/OpenTelemetry.Tests/Trace/TracerProviderSdkTest.cs b/test/OpenTelemetry.Tests/Trace/TracerProviderSdkTest.cs
index a94ebfeee1e..f93e3d13373 100644
--- a/test/OpenTelemetry.Tests/Trace/TracerProviderSdkTest.cs
+++ b/test/OpenTelemetry.Tests/Trace/TracerProviderSdkTest.cs
@@ -1303,6 +1303,35 @@ public void BuilderTypeDoesNotChangeTest()
         Assert.NotNull(provider);
     }
 
+    [Fact]
+    public void CheckActivityLinksAddedAfterActivityCreation()
+    {
+        var exportedItems = new List<Activity>();
+        using var source = new ActivitySource($"{Utils.GetCurrentMethodName()}.1");
+        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+                .SetSampler(new AlwaysOnSampler())
+                .AddInMemoryExporter(exportedItems)
+                .AddSource(source.Name)
+                .Build();
+
+        var link1 = new ActivityLink(new ActivityContext(ActivityTraceId.CreateRandom(), ActivitySpanId.CreateRandom(), ActivityTraceFlags.Recorded));
+        var link2 = new ActivityLink(new ActivityContext(ActivityTraceId.CreateRandom(), ActivitySpanId.CreateRandom(), ActivityTraceFlags.Recorded));
+
+        using (var activity = source.StartActivity("root"))
+        {
+            activity?.AddLink(link1);
+            activity?.AddLink(link2);
+        }
+
+        Assert.Single(exportedItems);
+        var exportedActivity = exportedItems[0];
+        Assert.Equal(2, exportedActivity.Links.Count());
+
+        // verify that the links retain the order as they were added.
+        Assert.Equal(link1.Context, exportedActivity.Links.ElementAt(0).Context);
+        Assert.Equal(link2.Context, exportedActivity.Links.ElementAt(1).Context);
+    }
+
     public void Dispose()
     {
         GC.SuppressFinalize(this);