Add Distributed Tracing Doc #22617
Add Distributed Tracing Doc #22617
Conversation
Co-authored-by: Youssef Victor <[email protected]>
There was a problem hiding this comment.
After applying the suggestions, this LGTM @tarekgh
I'll 
now.
|
Hi @BillWagner, do you know how long it takes to have this show-up publicly in the docs? |
|
@tarekgh We publish nightly (business days). It should be live tomorrow by 7:00 am PST. |
| - <xref:System.Diagnostics.Activity?displayProperty=nameWithType> class which allows storing and accessing diagnostics context and consuming it with logging system. | ||
| - <xref:System.Diagnostics.DiagnosticSource?displayProperty=nameWithType> that allows code to be instrumented for production-time logging of rich data payloads for consumption within the process that was instrumented. | ||
|
|
||
| Here is an example shows how to publish tracing data from the HTTP incoming requests: |
There was a problem hiding this comment.
I'd recommend we not lead with this example because it is refering to the older APIs and it is unlikely that most developers are going to be writing their own protocol servers. Instead we could jump right down to the .NET 5.0 stuff
| .NET 5.0 has extended the capability of the distributed tracing to allow the [OpenTelemetry](https://opentelemetry.io/) tracing scenarios, added Sampling capabilities, simplified the tracing coding pattern, and made the listening to the Activity events easier and flexible. | ||
|
|
||
| > [!NOTE] | ||
| > To access all added .NET 5.0 capabilities, ensure referencing the [System.Diagnostics.DiagnosticSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) NuGet package version 5.0 or later. This package can be used in libraries and apps targeting any supported version of the .NET Framework, .NET Core, and .NET Standard. If targeting .NET 5.0 or later, no need to manually reference the package as it is included in the shared library installed with the .NET SDK. |
There was a problem hiding this comment.
To access all added .NET 5.0 capabilities, ensure your application references the
There was a problem hiding this comment.
This may need to mention application or library I guess.
| .NET 5.0 has extended the capability of the distributed tracing to allow the [OpenTelemetry](https://opentelemetry.io/) tracing scenarios, added Sampling capabilities, simplified the tracing coding pattern, and made the listening to the Activity events easier and flexible. | ||
|
|
||
| > [!NOTE] | ||
| > To access all added .NET 5.0 capabilities, ensure referencing the [System.Diagnostics.DiagnosticSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) NuGet package version 5.0 or later. This package can be used in libraries and apps targeting any supported version of the .NET Framework, .NET Core, and .NET Standard. If targeting .NET 5.0 or later, no need to manually reference the package as it is included in the shared library installed with the .NET SDK. |
There was a problem hiding this comment.
... If targeting .NET 5.0 or later, there is no need ...
| .NET 5.0 has extended the capability of the distributed tracing to allow the [OpenTelemetry](https://opentelemetry.io/) tracing scenarios, added Sampling capabilities, simplified the tracing coding pattern, and made the listening to the Activity events easier and flexible. | ||
|
|
||
| > [!NOTE] | ||
| > To access all added .NET 5.0 capabilities, ensure referencing the [System.Diagnostics.DiagnosticSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) NuGet package version 5.0 or later. This package can be used in libraries and apps targeting any supported version of the .NET Framework, .NET Core, and .NET Standard. If targeting .NET 5.0 or later, no need to manually reference the package as it is included in the shared library installed with the .NET SDK. |
There was a problem hiding this comment.
... the shared library installed with the .NET Runtime
|
|
||
| ### ActivitySource | ||
|
|
||
| First step to publish tracing data is to create instance of the ActivitySource class. The ActivitySource is the class provides APIs to create and start Activity objects and to register ActivityListener objects to listen to the Activity events. |
There was a problem hiding this comment.
The first step to publish is to create an instance ...
|
|
||
| ### ActivitySource | ||
|
|
||
| First step to publish tracing data is to create instance of the ActivitySource class. The ActivitySource is the class provides APIs to create and start Activity objects and to register ActivityListener objects to listen to the Activity events. |
There was a problem hiding this comment.
The ActivitySource is the class that provides APIs
|
|
||
| - Create the ActivitySource once and store it in a static variable and use that instance as long as needed. | ||
|
|
||
| - The source name passed to the constructor has to be unique to avoid the conflicts with any other sources. It is recommended to use hierarchical name contains the parts, the company name, the component name, and the source name. For example, `Microsoft.System.HttpClient.HttpInOutRequests`. |
There was a problem hiding this comment.
The source name passed to the constructor has to be unique to avoid the conflicts with any other sources. It is recommended to use a hierarchical name contains the parts, the company name, the component name, and the source name. For example, Microsoft.System.HttpClient.HttpInOutRequests.
|
|
||
| - The source name passed to the constructor has to be unique to avoid the conflicts with any other sources. It is recommended to use hierarchical name contains the parts, the company name, the component name, and the source name. For example, `Microsoft.System.HttpClient.HttpInOutRequests`. | ||
|
|
||
| - The version parameter is optional. It is recommended to provide the version in case plan to release multiple versions of the library or the application and want to distinguish between the sources of different versions. |
There was a problem hiding this comment.
It is recommended to provide the version in case you plan to release multiple versions of the library or the application and want to distinguish between the sources of different versions.
No description provided.