issue 44282

Author: Cam Soper

docs/core/compatibility/10.0.md

@@ -17,9 +17,10 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 
 ## Core .NET libraries
 
-| Title                                                                                    | Type of change      | Introduced version |
-|------------------------------------------------------------------------------------------|---------------------|--------------------|
-| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md)  | Source incompatible | Preview 1          |
+| Title                                                                                                                      | Type of change      | Introduced version |
+|----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
+| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md)                                    | Source incompatible | Preview 1          |
+| [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change   | Preview 1          |
 
 ## Windows Forms
 

docs/core/compatibility/core-libraries/10.0/activity-sampling.md

@@ -0,0 +1,60 @@
+---
+title: "Breaking change: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior changes"
+description: Learn about the .NET 10.0 breaking change in core .NET libraries where ActivitySource.CreateActivity and ActivitySource.StartActivity behavior is modified.
+ms.date: 01/30/2025
+---
+# ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
+
+The <xref:System.Diagnostics.ActivitySource.CreateActivity*?displayProperty=nameWithType> and <xref:System.Diagnostics.ActivitySource.StartActivity*?displayProperty=nameWithType> APIs only return an `Activity` when there is a registered listener which decides the instance should be created. This is generally known as sampling.
+
+The <xref:System.Diagnostics.ActivitySamplingResult?displayProperty=nameWithType> enum defines the possible sampling decisions.
+
+When creating an `Activity` without a parent, `ActivitySamplingResult` drives whether the `Activity` is created and then how the `Recorded` and `IsAllDataRequested` properties are set:
+
+|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested|
+|---|---|---|---|
+|None|No|||
+|PropagationData|Yes|False|False|
+|AllData|Yes|False|True|
+|AllDataAndRecorded|Yes|True|True|
+
+It is also possible to create an `Activity` with a parent. The parent could be in the same process, or it could be a remote parent propagated to the current process.
+
+## Previous behavior
+
+When creating an `Activity` as `PropagationData` with a parent marked as `Recorded`:
+
+|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested|
+|---|---|---|---|
+|PropagationData|Yes|True|False|
+
+## New behavior
+
+When creating an `Activity` as `PropagationData` with a parent marked as `Recorded`:
+
+|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested|
+|---|---|---|---|
+|PropagationData|Yes|False|False|
+
+## Version introduced
+
+.NET 10 Preview 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The existing behavior does not follow the OpenTelemetry specification.
+
+## Recommended action
+
+Users who have implemented `ActivityListener.Sample` directly AND use `ActivitySamplingResult.PropagationData` should verify they are not reliant on the flawed behavior. `Activity.ActivityTraceFlags` may be set to `Recorded` after the `CreateActivity` or `StartActivity` call to restore the previous behavior.
+
+Users using OpenTelemetry .NET should verify their sampler configuration. The default OpenTelemetry .NET configuration uses a parent-based algorithm which is not impacted. Only users who have customized the sampler should verify the behavior.
+
+## Affected APIs
+
+- <xref:System.Diagnostics.ActivitySource.CreateActivity?displayProperty=fullName>
+- <xref:System.Diagnostics.ActivitySource.StartActivity?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -12,6 +12,8 @@ items:
             items:
               - name: API obsoletions with non-default diagnostic IDs
                 href: core-libraries/10.0/obsolete-apis.md
+              - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
+                href: core-libraries/10.0/activity-sampling.md
           - name: Windows Forms
             items:
               - name: TreeView checkbox image truncation
@@ -1316,6 +1318,8 @@ items:
             items:
               - name: API obsoletions with non-default diagnostic IDs
                 href: core-libraries/10.0/obsolete-apis.md
+              - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
+                href: core-libraries/10.0/activity-sampling.md
           - name: .NET 9
             items:
               - name: Adding a ZipArchiveEntry sets header general-purpose bit flags

docs/fundamentals/syslib-diagnostics/syslib0060.md

@@ -1,7 +1,7 @@
 ---
 title: SYSLIB0060 warning - Rfc2898DeriveBytes constructors are obsolete
 description: Learn about the obsoletion of Rfc2898DeriveBytes constructors. Use of these constructors generates compile-time warning SYSLIB0060.
-ms.date: 01/01/2025
+ms.date: 01/30/2025
 f1_keywords:
   - SYSLIB0060
 ---