Merge branch 'main' into sdk-metrics-exemplar-concurrency

Author: utpilla

docs/trace/README.md

@@ -95,6 +95,30 @@ or
 > [!NOTE]
 > Activities which are not yet finished/stopped will not be exported.
 
+:stop_sign: You should avoid calling
+[Activity.AddEvent](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity.addevent)
+in a loop. Activities are not designed to handle hundreds or thousands of
+events, a better model is to use [correlated
+logs](../logs/README.md#log-correlation) or
+[Activity.Links](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity.links).
+
+> [!WARNING]
+> The following code is not modeling `Activity.Events` correctly, and is very
+  likely to have usability and performance problems.
+
+```csharp
+private static async Task Test()
+{
+    Activity activity = Activity.Current;
+
+    while (true)
+    {
+        activity.AddEvent(new ActivityEvent("Processing background task."));
+        await Task.Delay(1000);
+    }
+}
+```
+
 ## TracerProvider Management
 
 :stop_sign: You should avoid creating `TracerProvider` instances too frequently,