First draft of a doc for Tracing in networking #42830
Conversation
|
@antonfirsov - how are you doing with a reference page for the new spans? |
| @@ -26,122 +26,48 @@ There are two parts to using metrics in a .NET app: | |||
|
|
|||
| This section demonstrates various methods to collect and view System.Net metrics. | |||
|
|
|||
| ### Example app | |||
| ### .NET Aspire | |||
There was a problem hiding this comment.
Are we sure we want to entirely replace this paragraph instead of eg. only replacing the prometheus+grafana part with the aspire example? The original example app is simple and self-contained and the paragraph also demonstrates dotnet-monitor.
|
|
||
| For the sake of this tutorial, create a simple app that sends HTTP requests to various endpoints in parallel. | ||
| The simplest solution for collecting metrics for ASP.NET applications is to use [.NET Aspire](/dotnet/aspire/get-started/aspire-overview) which is a set of extensions to .NET to make it easy to create and work with distributed applications. One of the benefits of using .NET Aspire is that telemetry is built in, using the OpenTelemetry libraries for .NET. The default project templates for .NET Aspire contain a `ServiceDefaults` project, part of which is to setup and configure OTel. The Service Defaults project is referenced and initialized by each service in a .NET Aspire solution. |
There was a problem hiding this comment.
for ASP.NET applications
This article is not supposed to be about ASP.NET, it should focus on System.Net.* stuff.
The simplest solution
I would prefer to use a less opinionated language. In our docs we now reference a wide range of tools (Application Insights, Prometheus+Grafana and now Aspire) which became somewhat confusing on it's own. Assuming that we don't plan to harmonize everything (=push for a particular solution against others) I would let the user decide what is simplest for their use-case.
There was a problem hiding this comment.
This telemetry is mostly going to be used in server apps - which today means ASP.NET. Its less about the web server and more about the host + builder pattern which is the required infrastructure.
What we should stop doing is having many different docs talk about the same concepts but implementing them differently. Its very confusing for users to know what patterns that they should be using. I think uniting around ServiceDefaults is going to provide the common infrastructure (that doesn't need to change on a per-project basis) and lead to more success.
|
|
||
| These spans are probably too verbose for use 24x7 in production scenarios with high workloads - they are somewhat noisy and this level of data is not normally needed. However if you are trying to diagnose connection issues or get a deeper understanding of how network and connection latency is affecting your services, then they provide insight that is hard to collect by other means. | ||
|
|
||
| Note: When enabled, the http connection span is linked to from HttpClient request spans. As an http connection can be long lived, this could result in many links to the connection span from each of the request spans. Some APM monitoring tools aggresively walk links between spans to build up their views and so including this span may cause issues when the tools were not designed to account for large numbers of links. |
There was a problem hiding this comment.
| Note: When enabled, the http connection span is linked to from HttpClient request spans. As an http connection can be long lived, this could result in many links to the connection span from each of the request spans. Some APM monitoring tools aggresively walk links between spans to build up their views and so including this span may cause issues when the tools were not designed to account for large numbers of links. | |
| > [!NOTE] | |
| > When enabled, the http connection span is linked to from HttpClient request spans. As an http connection can be long lived, this could result in many links to the connection span from each of the request spans. Some APM monitoring tools aggresively walk links between spans to build up their views and so including this span may cause issues when the tools were not designed to account for large numbers of links. |
Moreover, it would make sense to draw attention to the need to upgrade to .NET Aspire 9.0 (eg. via Upgrade Assistant) since Span Links are not supported in 8.0.
| .AddSource("Experimental.System.Net.NameResolution") | ||
| .AddSource("Experimental.System.Net.Sockets") | ||
| .AddSource("Experimental.System.Net.Security") | ||
| .AddSource("Experimental.System.Net.Http.Connections"); |
There was a problem hiding this comment.
| .AddSource("Experimental.System.Net.NameResolution") | |
| .AddSource("Experimental.System.Net.Sockets") | |
| .AddSource("Experimental.System.Net.Security") | |
| .AddSource("Experimental.System.Net.Http.Connections"); | |
| .AddSource("Experimental.System.Net.*"); |
.NET 9 introduced additions to `System.Net` distributed tracing which define a contract following OTel recommendations: - dotnet/runtime#104251 adjusted the HTTP client request activity so it natively complies with OTel recommendations. This included adding standard tags. - dotnet/runtime#103922 introduced activities breaking down the HTTP connection setup. This PR documents the activities together with their attributes in a manner similar to the metrics docs added by #37213. The matching semconv PR is open-telemetry/semantic-conventions#1192. Conceptual docs are being introduced in #42830. Moreover, the PR also adjusts certain parts of the metrics doc in order to make it more accurate, synchronize it with the activities doc and incorporate the changes from #42810. --------- Co-authored-by: Genevieve Warren <[email protected]> Co-authored-by: Miha Zupan <[email protected]>
Summary
Adds a new page for Tracing as part of Networking.
Work to be done:
Internal previews