[Instrumentation.AspNet] refine documentation (#3349)

Co-authored-by: Martin Costello <[email protected]>

Author: Kielek

src/OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule/README.md

@@ -9,8 +9,13 @@
 [![NuGet download count badge](https://img.shields.io/nuget/dt/OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule)](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule/)
 [![codecov.io](https://codecov.io/gh/open-telemetry/opentelemetry-dotnet-contrib/branch/main/graphs/badge.svg?flag=unittests-Instrumentation.AspNet)](https://app.codecov.io/gh/open-telemetry/opentelemetry-dotnet-contrib?flags[0]=unittests-Instrumentation.AspNet)
 
-The ASP.NET Telemetry HttpModule enables distributed tracing of incoming ASP.NET
-requests using the OpenTelemetry API.
+The ASP.NET Telemetry HttpModule is a skeleton to enable distributed tracing
+and metrics of incoming ASP.NET requests using the OpenTelemetry API.
+
+> [!NOTE]
+> This package is a [pre-release](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/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.
 
 ## Usage
 
@@ -19,7 +24,7 @@ requests using the OpenTelemetry API.
 If you are using the traditional `packages.config` reference style, a
 `web.config` transform should run automatically and configure the
 `TelemetryHttpModule` for you. If you are using the more modern PackageReference
-style, this may be needed to be done manually. For more information, see:
+style, this may need to be done manually. For more information, see:
 [Migrate from packages.config to
 PackageReference](https://docs.microsoft.com/nuget/consume-packages/migrate-packages-config-to-package-reference).
 
@@ -37,65 +42,14 @@ To configure your `web.config` manually, add this:
 </system.webServer>
 ```
 
-### Step 2: Register a listener
+### Step 2: Register hooks
 
-`TelemetryHttpModule` registers an
-[ActivitySource](https://docs.microsoft.com/dotnet/api/system.diagnostics.activitysource)
-with the name `OpenTelemetry.Instrumentation.AspNet`. By default, .NET
-`ActivitySource` will not generate any `Activity` objects unless there is
-a registered listener.
+`TelemetryHttpModule` provides hooks to create and manage activities and metrics.
 
-To register a listener automatically using OpenTelemetry, please use the
-[OpenTelemetry.Instrumentation.AspNet](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet/)
+To automatically register the entire infrastructure using OpenTelemetry, please
+use the [OpenTelemetry.Instrumentation.AspNet](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet/)
 NuGet package.
 
-To register a listener manually, use code such as the following:
-
-```csharp
-using System.Diagnostics;
-using System.Web;
-using System.Web.Http;
-using System.Web.Mvc;
-using System.Web.Routing;
-using OpenTelemetry.Instrumentation.AspNet;
-
-namespace Examples.AspNet;
-
-public class WebApiApplication : HttpApplication
-{
-    private ActivityListener aspNetActivityListener;
-
-    protected void Application_Start()
-    {
-        this.aspNetActivityListener = new ActivityListener
-        {
-            ShouldListenTo = (activitySource) =>
-            {
-                // Only listen to TelemetryHttpModule's ActivitySource.
-                return activitySource.Name == "OpenTelemetry.Instrumentation.AspNet";
-            },
-            Sample = (ref ActivityCreationOptions<ActivityContext> options) =>
-            {
-                // Sample everything created by TelemetryHttpModule's ActivitySource.
-                return ActivitySamplingResult.AllDataAndRecorded;
-            },
-        };
-
-        ActivitySource.AddActivityListener(this.aspNetActivityListener);
-
-        GlobalConfiguration.Configure(WebApiConfig.Register);
-
-        AreaRegistration.RegisterAllAreas();
-        RouteConfig.RegisterRoutes(RouteTable.Routes);
-    }
-
-    protected void Application_End()
-    {
-        this.aspNetActivityListener?.Dispose();
-    }
-}
-```
-
 ## Options
 
 `TelemetryHttpModule` provides a static options property
@@ -105,7 +59,7 @@ public class WebApiApplication : HttpApplication
 ### TextMapPropagator
 
 `TextMapPropagator` controls how trace context will be extracted from incoming
-Http request messages. By default, [W3C Trace
+HTTP request messages. By default, [W3C Trace
 Context](https://www.w3.org/TR/trace-context/) is enabled.
 
 The OpenTelemetry API ships with a handful of [standard
@@ -134,10 +88,13 @@ default supports W3C Trace Context & Baggage.
 
 ### Events
 
-`OnRequestStartedCallback`, `OnRequestStoppedCallback`, & `OnExceptionCallback`
+`OnRequestStartedCallback`, `OnRequestStoppedCallback`, and `OnExceptionCallback`
 are provided on `TelemetryHttpModuleOptions` and will be fired by the
 `TelemetryHttpModule` as requests are processed.
 
-A typical use case for these events is to add information (tags, events, and/or
-links) to the created `Activity` based on the request, response, and/or
-exception event being fired.
+A typical use case for the `OnRequestStartedCallback` event is to create an activity
+based on the `HttpContextBase` and `ActivityContext`.
+
+`OnRequestStoppedCallback` and `OnExceptionCallback` are needed to add
+information (tags, events, and/or links) to the created `Activity` based on the
+request, response, and/or exception event being fired.

src/OpenTelemetry.Instrumentation.AspNet/README.md

@@ -12,7 +12,7 @@
 This is an [Instrumentation
 Library](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library),
 which instruments [ASP.NET](https://docs.microsoft.com/aspnet/overview) and
-collect metrics and traces about incoming web requests.
+collects metrics and traces about incoming web requests.
 
 > [!NOTE]
 > This package is a [pre-release](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/VERSIONING.md#pre-releases).
@@ -36,8 +36,8 @@ dotnet add package OpenTelemetry.Instrumentation.AspNet
 `OpenTelemetry.Instrumentation.AspNet` requires adding an additional HttpModule
 to your web server. This additional HttpModule is shipped as part of
 [`OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule/)
-which is implicitly brought by `OpenTelemetry.Instrumentation.AspNet`. The
-following shows changes required to your `Web.config` when using IIS web server.
+which is implicitly referenced by `OpenTelemetry.Instrumentation.AspNet`. The
+following shows the changes required to your `Web.config` when using IIS web server.
 
 ```xml
 <system.webServer>
@@ -146,7 +146,7 @@ data collection for anything NOT recorded by the sampler. The sampler approach
 will reduce the impact on the process being instrumented for all filtered
 requests.
 
-This instrumentation by default collects all the incoming http requests. It
+This instrumentation by default collects all incoming HTTP requests. It
 allows filtering of requests by using the `Filter` function in
 `AspNetTraceInstrumentationOptions`. This defines the condition for allowable
 requests. The Filter receives the `HttpContextBase` of the incoming request, and
@@ -173,7 +173,7 @@ This instrumentation library provides `EnrichWithHttpRequest`,
 `EnrichWithHttpResponse` and `EnrichWithException` options that can be used to
 enrich the activity with additional information from the raw `HttpRequestBase`,
 `HttpResponseBase` and `Exception` objects respectively. These actions are called
-only when `activity.IsAllDataRequested` is `true`. It contains the activity
+only when `activity.IsAllDataRequested` is `true`. They contain the activity
 itself (which can be enriched) and the actual raw object.
 
 The following code snippet shows how to enrich the activity using all 3
@@ -202,10 +202,11 @@ this.tracerProvider = Sdk.CreateTracerProviderBuilder()
     .Build();
 ```
 
-[Processor](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/docs/trace/extending-the-sdk/README.md#processor),
+[Processor](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/docs/trace/extending-the-sdk/README.md#processor)
 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 `HttpRequestBase` and `HttpResponseBase`.
+The `EnrichWithHttpRequest`, `EnrichWithHttpResponse`, and `EnrichWithException`
+options are specific to this instrumentation, and are provided to get
+access to `HttpRequestBase`, `HttpResponseBase`, and `Exception` respectively.
 
 ### RecordException
 
@@ -221,13 +222,13 @@ This instrumentation can be configured to change the default behavior by using
 ### Metric Enrich
 
 This option allows one to enrich the metric with additional information from
-the `HttpContextBase`. The `Enrich` action is always called unless the metric was
-filtered. The callback allows for modifying the tag list. If the callback
-throws an exception the metric will still be recorded.
+the `HttpContextBase`. The `EnrichWithHttpContext` action is always called
+unless the metric was filtered. The callback allows for modifying the tag list.
+If the callback throws an exception the metric will still be recorded.
 
 ```csharp
 this.meterProvider = Sdk.CreateMeterProviderBuilder()
-    .AddAspNetInstrumentation(options => options.Enrich =
+    .AddAspNetInstrumentation(options => options.EnrichWithHttpContext =
         (HttpContextBase context, ref TagList tags) =>
     {
         // Add request content type to the metric tags.