Distributed tracing in networking (#44063)

Introduce conceptual docs on distributed tracing in System.Net. Leverage Aspire Dashboards to demo the traces.

Author: antonfirsov

docs/core/diagnostics/distributed-tracing-builtin-activities.md

@@ -11,6 +11,9 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics
 
 ## System.Net activities
 
+> [!TIP]
+> For a comprehensive guide about collecting and reporting `System.Net` traces, see [Networking distributed traces in .NET](../../fundamentals/networking/telemetry/metrics.md).
+
 ### HTTP client request
 
 <xref:System.Net.Http.SocketsHttpHandler> and <xref:System.Net.Http.HttpClientHandler> report the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by <xref:System.Net.Http.HttpClient>'s send overloads during the time interval the underlying handler completes the request. Completing the request includes the time up to reading response headers from the network stream. It doesn't include the time spent reading the response body. <xref:System.Net.Http.SocketsHttpHandler> may retry requests, for example, on connection failures or HTTP version downgrades. Retries are not reported as separate *HTTP client request* activities.

docs/core/diagnostics/media/aspire-starter.png

@@ -41,6 +41,9 @@
     // Metrics provides by ASP.NET Core in .NET 8
     .AddMeter("Microsoft.AspNetCore.Hosting")
     .AddMeter("Microsoft.AspNetCore.Server.Kestrel")
+    // Metrics provided by System.Net libraries
+    .AddMeter("System.Net.Http")
+    .AddMeter("System.Net.NameResolution")
     .AddPrometheusExporter());
 
 // Add Tracing for ASP.NET Core and our custom ActivitySource and export to Jaeger
@@ -88,6 +91,24 @@
 app.MapGet("/NestedGreeting", SendNestedGreeting);
 //</Snippet_MapNested>
 
+//<Snippet_ClientStress>
+app.MapGet("/ClientStress", async Task<string> (ILogger<Program> logger, HttpClient client) =>
+{
+    string[] uris = ["http://example.com", "http://httpbin.org/get", "https://example.com", "https://httpbin.org/get"];
+    await Parallel.ForAsync(0, 50, async (_, ct) =>
+    {
+        string uri = uris[Random.Shared.Next(uris.Length)];
+
+        try
+        {
+            await client.GetAsync(uri, ct);
+            logger.LogInformation($"{uri} - done.");
+        }
+        catch { logger.LogInformation($"{uri} - failed."); }
+    });
+    return "Sent 50 requests to example.com and httpbin.org.";
+});
+//</Snippet_ClientStress>
 
 #if !AZURE_MONITOR
 //<Snippet_Prometheus>
@@ -99,7 +120,7 @@
 app.Run();
 
 //<Snippet_SendGreeting>
-async Task<String> SendGreeting(ILogger<Program> logger)
+async Task<string> SendGreeting(ILogger<Program> logger)
 {
     // Create a new Activity scoped to the method
     using var activity = greeterActivitySource.StartActivity("GreeterActivity");

docs/core/diagnostics/media/grafana-http11-connections.png

@@ -0,0 +1,22 @@
+The Aspire Service Defaults project provides an easy way to configure OTel for ASP.NET projects, *even if not using the rest of .NET Aspire* such as the AppHost for orchestration. The Service Defaults project is available as a project template via Visual Studio or `dotnet new`. It configures OTel and sets up the OTLP exporter. You can then use the [OTel environment variables](https://github.com/open-telemetry/opentelemetry-dotnet/tree/c94c422e31b2a5181a97b2dcf4bdc984f37ac1ff/src/OpenTelemetry.Exporter.OpenTelemetryProtocol#exporter-configuration) to configure the OTLP endpoint to send telemetry to, and provide the resource properties for the application.
+
+The steps to use *ServiceDefaults* outside .NET Aspire are:
+
+1. Add the *ServiceDefaults* project to the solution using Add New Project in Visual Studio, or use `dotnet new`:
+
+    ```dotnetcli
+    dotnet new aspire-servicedefaults --output ServiceDefaults
+    ```
+
+1. Reference the *ServiceDefaults* project from your ASP.NET application. In Visual Studio, select **Add** > **Project Reference** and select the **ServiceDefaults** project"
+1. Call the OpenTelemetry setup function `ConfigureOpenTelemetry()` as part of your application builder initialization.
+
+    ``` csharp
+    var builder = WebApplication.CreateBuilder(args)
+    builder.ConfigureOpenTelemetry(); // Extension method from ServiceDefaults.
+    var app = builder.Build();
+    app.MapGet("/", () => "Hello World!");
+    app.Run();
+    ```
+
+For a full walkthrough, see [Example: Use OpenTelemetry with OTLP and the standalone Aspire Dashboard](../../../../core/diagnostics/observability-otlp-example.md).

docs/core/diagnostics/snippets/OTel-Prometheus-Grafana-Jaeger/csharp/Program.cs

@@ -0,0 +1,7 @@
+A simple way to collect traces and metrics in ASP.NET applications is to use [.NET Aspire](/dotnet/aspire/get-started/aspire-overview). .NET Aspire 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. Each service in the .NET Aspire solution has a reference to the Service Defaults project. The services use it to set up and configure OTel.
+
+The Service Defaults project template includes the OTel SDK, ASP.NET, HttpClient, and Runtime Instrumentation packages. These instrumentation components are configured in the [Extensions.cs](https://github.com/dotnet/aspire/blob/main/src/Aspire.ProjectTemplates/templates/aspire-servicedefaults/Extensions.cs) file. To support telemetry visualization in Aspire Dashboard, the Service Defaults project also includes the OTLP exporter by default.
+
+Aspire Dashboard is designed to bring telemetry observation to the local debug cycle, which enables developers to ensure that the applications are producing telemetry. The telemetry visualization also helps to diagnose those applications locally. Being able to observe the calls between services is as useful at debug time as in production. The .NET Aspire dashboard is launched automatically when you <kbd>F5</kbd> the `AppHost` Project from Visual Studio or `dotnet run` the `AppHost` project from command line.