Add breaking change for default ActivityIdFormat

docs/core/compatibility/3.1-5.0.md

@@ -92,11 +92,16 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v
 
 ## Core .NET libraries
 
+- [Default ActivityIdFormat is W3C](#default-activityidformat-is-w3c)
 - [Behavior change for Vector2.Lerp and Vector4.Lerp](#behavior-change-for-vector2lerp-and-vector4lerp)
 - [SSE and SSE2 CompareGreaterThan methods properly handle NaN inputs](#sse-and-sse2-comparegreaterthan-methods-properly-handle-nan-inputs)
 - [CounterSet.CreateCounterSetInstance now throws InvalidOperationException if instance already exist](#countersetcreatecountersetinstance-now-throws-invalidoperationexception-if-instance-already-exists)
 - [Microsoft.DotNet.PlatformAbstractions package removed](#microsoftdotnetplatformabstractions-package-removed)
 
+[!INCLUDE [default-activityidformat-changed](../../../includes/core-changes/corefx/5.0/default-activityidformat-changed.md)]
+
+***
+
 [!INCLUDE [vector-lerp-behavior-change](../../../includes/core-changes/corefx/5.0/vector-lerp-behavior-change.md)]
 
 ***

docs/core/compatibility/corefx.md

@@ -11,6 +11,7 @@ The following breaking changes are documented on this page:
 
 | Breaking change | Version introduced |
 | - | :-: |
+| [Default ActivityIdFormat is W3C](#default-activityidformat-is-w3c) | 5.0 |
 | [Behavior change for Vector2.Lerp and Vector4.Lerp](#behavior-change-for-vector2lerp-and-vector4lerp) | 5.0 |
 | [SSE and SSE2 CompareGreaterThan methods properly handle NaN inputs](#sse-and-sse2-comparegreaterthan-methods-properly-handle-nan-inputs) | 5.0 |
 | [CounterSet.CreateCounterSetInstance now throws InvalidOperationException if instance already exist](#countersetcreatecountersetinstance-now-throws-invalidoperationexception-if-instance-already-exists) | 5.0 |
@@ -39,6 +40,10 @@ The following breaking changes are documented on this page:
 
 ## .NET 5.0
 
+[!INCLUDE [default-activityidformat-changed](../../../includes/core-changes/corefx/5.0/default-activityidformat-changed.md)]
+
+***
+
 [!INCLUDE [vector-lerp-behavior-change](../../../includes/core-changes/corefx/5.0/vector-lerp-behavior-change.md)]
 
 ***

includes/core-changes/corefx/5.0/default-activityidformat-changed.md

@@ -0,0 +1,59 @@
+### Default ActivityIdFormat is W3C
+
+The default identifier format for activity (<xref:System.Diagnostics.Activity.DefaultIdFormat?displayProperty=nameWithType>) is now <xref:System.Diagnostics.ActivityIdFormat.W3C?displayProperty=nameWithType>.
+
+#### Change description
+
+The W3C activity ID format was introduced in .NET Core 3.0 as an alternative to the hierarchical ID format. However, to preserve compatibility, the W3C format wasn't made the default until .NET 5.0. The default was changed in .NET 5.0 because the [W3C format has been ratified](https://www.w3.org/TR/trace-context/) and gained traction across multiple language implementations.
+
+If your app targets a platform other than .NET 5.0 or later, it will experience the old behavior, where <xref:System.Diagnostics.ActivityIdFormat.Hierarchical> is the default format. This default applies to platforms net45+, netstandard1.1+, and netcoreapp (1.x, 2.x, and 3.x). In .NET 5.0 and later, <xref:System.Diagnostics.Activity.DefaultIdFormat?displayProperty=nameWithType> is set to <xref:System.Diagnostics.ActivityIdFormat.W3C?displayProperty=nameWithType>.
+
+#### Version introduced
+
+5.0 Preview 7
+
+#### Recommended action
+
+If your application is agnostic to the identifier that's used for distributed tracing, no action is needed. Libraries such as ASP.NET Core and <xref:System.Net.Http.HttpClient> can consume or propagate both versions of the <xref:System.Diagnostics.ActivityIdFormat>.
+
+If you require interoperability with existing systems, or current systems rely on the format of the identifier, you can preserve the old behavior by setting <xref:System.Diagnostics.Activity.DefaultIdFormat> to <xref:System.Diagnostics.ActivityIdFormat.Hierarchical?displayProperty=nameWithType>. Alternatively, you can set an AppContext switch in one of three ways:
+
+- In the project file.
+
+  ```xml
+  <ItemGroup>
+    <RuntimeHostConfigurationOption Include="System.Diagnostics.DefaultActivityIdFormatIsHierarchial" Value="true" />
+  </ItemGroup>
+  ```
+
+- In the *runtimeconfig.json* file.
+
+  ```json
+  {
+      "runtimeOptions": {
+          "configProperties": {
+              "System.Diagnostics.DefaultActivityIdFormatIsHierarchial": true
+          }
+      }
+  }
+  ```
+
+- Through an environment variable.
+
+  Set `DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL` to `true` or 1.
+
+#### Category
+
+Core .NET libraries
+
+#### Affected APIs
+
+- <xref:System.Diagnostics.Activity.DefaultIdFormat?displayProperty=fullName>
+
+<!--
+
+#### Affected APIs
+
+- `P:System.Diagnostics.Activity.DefaultIdFormat`
+
+-->