Description
Help us make content visible
Likely search terms would be 'OpenTelemetry', 'Distributed Tracing', 'Activity', 'ActivitySource', 'TraceId', and 'Span'
Some of those searches will find related material but they aren't that helpful on their own:
- https://docs.microsoft.com/en-us/dotnet/core/diagnostics/logging-tracing
Provides no conceptual information or guidance about how to do distributed tracing other than linking to the Activity API - https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=netcore-3.1
Has reference information for the API but minimal conceptual information, end-to-end workflows, related tooling or guidance for usage. The guidance that is present refers users to a previous usage style that doesn't support sampling. - https://docs.microsoft.com/en-us/azure/azure-monitor/app/distributed-tracing
This page has much better conceptual info, but is specific to ApplicationInsights and doesn't provide any information about how the Activity API can be used by developers to push data into these tooling experiences.
Describe the new article
-
Explain why this article is needed.
In .NET 5 we updated Activity APIs to better integrate with OpenTelemetry. We also created the ActivityListener API so that any code component could subscribe to distributed tracing information, not only OpenTelemetry. We need to describe these new capabilities to users so that they can benefit from our work. -
Suggest a location in the Table of Contents.
Conceptual info underneath https://docs.microsoft.com/en-us/dotnet/core/diagnostics/
Also include links to the conceptual info within API reference docs for Activity, ActivitySource, and ActivityListener -
Write an abstract. In one short paragraph, describe what this article will cover.
This article will describe what is distributed tracing, what is it useful for, and how to accomplish it using .NET. Guidance will be provided on how to use Activity, ActivitySource, and ActivityListener APIs to create and observe tracing information. We will also show how to use OpenTelemetry to integrate with a variety of distributed trace visualization tools.
-
Create an outline for the new article. We'll help review the outline and approve it before anyone writes the article.
- What is Distributed Tracing?
- What problems does Distributed Tracing help me solve?
- E2E example of visualizing distributed trace information for a locally deployed service using OpenTelemetry
- .NET has libraries that come pre-instrumented such as ASP.Net, thus some scenarios work out-of-the-box
- Azure specific example of distributed tracing (maybe this is a link to Azure docs?)
- Guidance on using ActivitySource and Activity to log custom information in a distributed trace
- Guidance on using ActivityListener to observe distributed trace information and doing custom data collection
Other notes:
- There is some past guidance here. Not all of it is accurate any longer and we should review to determine what remains pertinent.
- Some guidance that came up in another issue that we should remember to include