[HttpClient & Asp.Net Core] Update Readme.md (#5168)

open-telemetry · Dec 14, 2023 · 4842364 · 4842364
1 parent 2bccad8
commit 4842364
Show file tree

Hide file tree

Showing 2 changed files with 118 additions and 37 deletions.
diff --git a/src/OpenTelemetry.Instrumentation.AspNetCore/README.md b/src/OpenTelemetry.Instrumentation.AspNetCore/README.md
@@ -9,18 +9,13 @@ which instruments [ASP.NET Core](https://docs.microsoft.com/aspnet/core) and
 collect metrics and traces about incoming web requests. This instrumentation
 also collects traces from incoming gRPC requests using
 [Grpc.AspNetCore](https://www.nuget.org/packages/Grpc.AspNetCore).
+Instrumentation support for gRPC server requests is supported via an
+[experimental](#experimental-support-for-grpc-requests) feature flag.
 
-**Note: This component is based on the OpenTelemetry semantic conventions for
-[metrics](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md)
-and
-[traces](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md).
-These conventions are
-[Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md),
-and hence, this package is a [pre-release](../../VERSIONING.md#pre-releases).
-Until a [stable
-version](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/telemetry-stability.md)
-is released, there can be breaking changes. You can track the progress from
-[milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestone/23).**
+This component is based on the
+[v1.23](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http)
+of http semantic conventions. For details on the default set of attributes that
+are added, checkout [Traces](#traces) and [Metrics](#metrics) sections below.
 
 ## Steps to enable OpenTelemetry.Instrumentation.AspNetCore
 
@@ -31,7 +26,7 @@ Add a reference to the
 package. Also, add any other instrumentations & exporters you will need.
 
 ```shell
-dotnet add package --prerelease OpenTelemetry.Instrumentation.AspNetCore
+dotnet add package OpenTelemetry.Instrumentation.AspNetCore
 ```
 
 ### Step 2: Enable ASP.NET Core Instrumentation at application startup
@@ -66,6 +61,26 @@ public void ConfigureServices(IServiceCollection services)
 }
 ```
 
+Following list of attributes are added by default on activity. See
+[http-spans](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http/http-spans.md)
+for more details about each individual attribute:
+
+* `error.type`
+* `http.request.method`
+* `http.request.method_original`
+* `http.response.status_code`
+* `http.route`
+* `network.protocol.version`
+* `user_agent.original`
+* `server.address`
+* `server.port`
+* `url.path`
+* `url.query`
+* `url.scheme`
+
+[Enrich Api](#enrich) can be used if any additional attributes are
+required on activity.
+
 #### Metrics
 
 The following example demonstrates adding ASP.NET Core instrumentation with the
@@ -88,6 +103,20 @@ public void ConfigureServices(IServiceCollection services)
 }
 ```
 
+Following list of attributes are added by default on
+`http.server.request.duration` metric. See
+[http-metrics](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http/http-metrics.md)
+for more details about each individual attribute. `.NET8.0` and above supports
+additional metrics, see [list of metrics produced](#list-of-metrics-produced) for
+more details.
+
+* `error.type`
+* `http.response.status_code`
+* `http.request.method`
+* `http.route`
+* `network.protocol.version`
+* `url.scheme`
+
 #### List of metrics produced
 
 When the application targets `.NET6.0` or `.NET7.0`, the instrumentation emits
@@ -138,6 +167,8 @@ newer versions.
 
 ## Advanced configuration
 
+### Tracing
+
 This instrumentation can be configured to change the default behavior by using
 `AspNetCoreTraceInstrumentationOptions`, which allows adding [`Filter`](#filter),
 [`Enrich`](#enrich) as explained below.
@@ -166,7 +197,7 @@ services.AddOpenTelemetry()
         .AddConsoleExporter());
 ```
 
-### Filter
+#### Filter
 
 This instrumentation by default collects all the incoming http requests. It
 allows filtering of requests by using the `Filter` function in
@@ -194,7 +225,7 @@ instrumentation. OpenTelemetry has a concept of a
 [Sampler](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampling),
 and the `Filter` option does the filtering *after* the Sampler is invoked.
 
-### Enrich
+#### Enrich
 
 This instrumentation library provides `EnrichWithHttpRequest`,
 `EnrichWithHttpResponse` and `EnrichWithException` options that can be used to
@@ -231,13 +262,13 @@ is the general extensibility point to add additional properties to any activity.
 The `Enrich` option is specific to this instrumentation, and is provided to
 get access to `HttpRequest` and `HttpResponse`.
 
-### RecordException
+#### RecordException
 
 This instrumentation automatically sets Activity Status to Error if an unhandled
 exception is thrown. Additionally, `RecordException` feature may be turned on,
 to store the exception to the Activity itself as ActivityEvent.
 
-## Activity Duration and http.server.request.duration metric calculation
+## Activity duration and http.server.request.duration metric calculation
 
 `Activity.Duration` and `http.server.request.duration` values represents the
 time used to handle an inbound HTTP request as measured at the hosting layer of
@@ -254,6 +285,31 @@ The time ends when:
 * All response data has been sent.
 * The context data structures for the request are being disposed.
 
+## Experimental support for gRPC requests
+
+gRPC instrumentation can be enabled by setting
+`OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_ENABLE_GRPC_INSTRUMENTATION` flag to
+`True`. The flag can be set as an environment variable or via IConfiguration as
+shown below.
+
+```csharp
+var appBuilder = WebApplication.CreateBuilder(args);
+
+appBuilder.Configuration.AddInMemoryCollection(
+    new Dictionary<string, string?>
+    {
+        ["OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_ENABLE_GRPC_INSTRUMENTATION"] = "true",
+    });
+
+appBuilder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing
+    .AddAspNetCoreInstrumentation());
+```
+
+ Semantic conventions for RPC are still
+ [experimental](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/rpc)
+ and hence the instrumentation only offers it as an experimental feature.
+
 ## Troubleshooting
 
 This component uses an

diff --git a/src/OpenTelemetry.Instrumentation.Http/README.md b/src/OpenTelemetry.Instrumentation.Http/README.md
@@ -11,18 +11,10 @@ and
 [System.Net.HttpWebRequest](https://docs.microsoft.com/dotnet/api/system.net.httpwebrequest)
 and collects metrics and traces about outgoing HTTP requests.
 
-**Note: This component is based on the OpenTelemetry semantic conventions for
-[metrics](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md)
-and
-[traces](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md).
-These conventions are
-[Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md),
-and hence, this package is a [pre-release](../../VERSIONING.md#pre-releases).
-Until a [stable
-version](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/telemetry-stability.md)
-is released, there can be [breaking changes](./CHANGELOG.md). You can track the
-progress from
-[milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestone/23).**
+This component is based on the
+[v1.23](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http)
+of http semantic conventions. For details on the default set of attributes that
+are added, checkout [Traces](#traces) and [Metrics](#metrics) sections below.
 
 ## Steps to enable OpenTelemetry.Instrumentation.Http
 
@@ -33,7 +25,7 @@ Add a reference to the
 package. Also, add any other instrumentations & exporters you will need.
 
 ```shell
-dotnet add package --prerelease OpenTelemetry.Instrumentation.Http
+dotnet add package OpenTelemetry.Instrumentation.Http
 ```
 
 ### Step 2: Enable HTTP Instrumentation at application startup
@@ -65,6 +57,22 @@ public class Program
 }
 ```
 
+Following list of attributes are added by default on activity. See
+[http-spans](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http/http-spans.md)
+for more details about each individual attribute:
+
+* `error.type`
+* `http.request.method`
+* `http.request.method_original`
+* `http.response.status_code`
+* `network.protocol.version`
+* `server.address`
+* `server.port`
+* `url.full`
+
+[Enrich Api](#enrich-httpclient-api) can be used if any additional attributes are
+required on activity.
+
 #### Metrics
 
 The following example demonstrates adding `HttpClient` instrumentation with the
@@ -97,6 +105,21 @@ Refer to this
 [example](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNet/README.md)
 to see how to enable this instrumentation in an ASP.NET application.
 
+Following list of attributes are added by default on
+`http.client.request.duration` metric. See
+[http-metrics](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http/http-metrics.md)
+for more details about each individual attribute. `.NET8.0` and above supports
+additional metrics, see [list of metrics produced](#list-of-metrics-produced) for
+more details.
+
+* `error.type`
+* `http.request.method`
+* `http.response.status_code`
+* `network.protocol.version`
+* `server.address`
+* `server.port`
+* `url.scheme`
+
 #### List of metrics produced
 
 When the application targets `NETFRAMEWORK`, `.NET6.0` or `.NET7.0`, the
@@ -147,6 +170,8 @@ newer versions.
 
 ## Advanced configuration
 
+### Tracing
+
 This instrumentation can be configured to change the default behavior by using
 `HttpClientTraceInstrumentationOptions`. It is important to note that there are
 differences between .NET Framework and newer .NET/.NET Core runtimes which
@@ -155,9 +180,9 @@ govern what options are used. On .NET Framework, `HttpClient` uses the
 `HttpClient` API. As such, depending on the runtime, only one half of the
 "filter" & "enrich" options are used.
 
-### .NET & .NET Core
+#### .NET & .NET Core
 
-#### Filter HttpClient API
+##### Filter HttpClient API
 
 This instrumentation by default collects all the outgoing HTTP requests. It
 allows filtering of requests by using the `FilterHttpRequestMessage` function
@@ -189,7 +214,7 @@ to this instrumentation. OpenTelemetry has a concept of a
 and the `FilterHttpRequestMessage` option does the filtering *after* the Sampler
 is invoked.
 
-#### Enrich HttpClient API
+##### Enrich HttpClient API
 
 This instrumentation library provides options that can be used to
 enrich the activity with additional information. These actions are called
@@ -228,9 +253,9 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .Build();
 ```
 
-### .NET Framework
+#### .NET Framework
 
-#### Filter HttpWebRequest API
+##### Filter HttpWebRequest API
 
 This instrumentation by default collects all the outgoing HTTP requests. It
 allows filtering of requests by using the `FilterHttpWebRequest` function
@@ -262,7 +287,7 @@ this instrumentation. OpenTelemetry has a concept of a
 and the `FilterHttpWebRequest` option does the filtering *after* the Sampler is
 invoked.
 
-#### Enrich HttpWebRequest API
+##### Enrich HttpWebRequest API
 
 This instrumentation library provides options that can be used to
 enrich the activity with additional information. These actions are called
@@ -306,13 +331,13 @@ general extensibility point to add additional properties to any activity. The
 `Enrich` option is specific to this instrumentation, and is provided to get
 access to raw request, response, and exception objects.
 
-### RecordException
+#### RecordException
 
 This instrumentation automatically sets Activity Status to Error if the Http
 StatusCode is >= 400. Additionally, `RecordException` feature may be turned on,
 to store the exception to the Activity itself as ActivityEvent.
 
-## Activity Duration and http.client.request.duration metric calculation
+## Activity duration and http.client.request.duration metric calculation
 
 `Activity.Duration` and `http.client.request.duration` values represents the
 time the underlying client handler takes to complete the request. Completing the