[Instrumentation.AspNet] Improve enrich methods (open-telemetry#1824)

Author: Kielek

src/OpenTelemetry.Instrumentation.AspNet/.publicApi/PublicAPI.Unshipped.txt

@@ -5,8 +5,12 @@ OpenTelemetry.Instrumentation.AspNet.AspNetMetricsInstrumentationOptions.Enrich.
 OpenTelemetry.Instrumentation.AspNet.AspNetMetricsInstrumentationOptions.EnrichFunc
 OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions
 OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.AspNetTraceInstrumentationOptions() -> void
-OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.Enrich.get -> System.Action<System.Diagnostics.Activity!, string!, object!>?
-OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.Enrich.set -> void
+OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.EnrichWithException.get -> System.Action<System.Diagnostics.Activity!, System.Exception!>?
+OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.EnrichWithException.set -> void
+OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.EnrichWithHttpRequest.get -> System.Action<System.Diagnostics.Activity!, System.Web.HttpRequest!>?
+OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.EnrichWithHttpRequest.set -> void
+OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.EnrichWithHttpResponse.get -> System.Action<System.Diagnostics.Activity!, System.Web.HttpResponse!>?
+OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.EnrichWithHttpResponse.set -> void
 OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.Filter.get -> System.Func<System.Web.HttpContext!, bool>?
 OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.Filter.set -> void
 OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.RecordException.get -> bool

src/OpenTelemetry.Instrumentation.AspNet/AspNetTraceInstrumentationOptions.cs

@@ -55,11 +55,27 @@ public AspNetTraceInstrumentationOptions()
     /// </summary>
     /// <remarks>
     /// <para><see cref="Activity"/>: the activity being enriched.</para>
-    /// <para>string: the name of the event.</para>
-    /// <para>object: the raw object from which additional information can be extracted to enrich the activity.
-    /// The type of this object depends on the event, which is given by the above parameter.</para>
+    /// <para><see cref="HttpRequest"/>: the HttpRequest object from which additional information can be extracted to enrich the activity.</para>
     /// </remarks>
-    public Action<Activity, string, object>? Enrich { get; set; }
+    public Action<Activity, HttpRequest>? EnrichWithHttpRequest { get; set; }
+
+    /// <summary>
+    /// Gets or sets an action to enrich an Activity.
+    /// </summary>
+    /// <remarks>
+    /// <para><see cref="Activity"/>: the activity being enriched.</para>
+    /// <para><see cref="HttpResponse"/>: the HttpResponse object from which additional information can be extracted to enrich the activity.</para>
+    /// </remarks>
+    public Action<Activity, HttpResponse>? EnrichWithHttpResponse { get; set; }
+
+    /// <summary>
+    /// Gets or sets an action to enrich an Activity.
+    /// </summary>
+    /// <remarks>
+    /// <para><see cref="Activity"/>: the activity being enriched.</para>
+    /// <para><see cref="Exception"/>: the Exception object from which additional information can be extracted to enrich the activity.</para>
+    /// </remarks>
+    public Action<Activity, Exception>? EnrichWithException { get; set; }
 
     /// <summary>
     /// Gets or sets a value indicating whether the exception will be recorded as ActivityEvent or not.

src/OpenTelemetry.Instrumentation.AspNet/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Unreleased
+
+* **Breaking change** The `Enrich` callback option has been removed.
+  For better usability, it has been replaced by three separate options:
+  `EnrichWithHttpRequest`, `EnrichWithHttpResponse` and `EnrichWithException`.
+  Previously, the single `Enrich` callback required the consumer to detect
+  which event triggered the callback to be invoked (e.g., request start,
+  response end, or an exception) and then cast the object received to the
+  appropriate type: `HttpRequest`, `HttpResponse`, or `Exception`. The separate
+  callbacks make it clear what event triggers them and there is no longer the
+  need to cast the argument to the expected type.
+  ([#1824](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/pull/1824))
+
 ## 1.8.0-beta.2
 
 Released 2024-Apr-17

src/OpenTelemetry.Instrumentation.AspNet/Implementation/HttpInListener.cs

@@ -102,7 +102,7 @@ private void OnStartActivity(Activity activity, HttpContext context)
 
             try
             {
-                this.options.Enrich?.Invoke(activity, "OnStartActivity", request);
+                this.options.EnrichWithHttpRequest?.Invoke(activity, request);
             }
             catch (Exception ex)
             {
@@ -135,7 +135,7 @@ private void OnStopActivity(Activity activity, HttpContext context)
 
             try
             {
-                this.options.Enrich?.Invoke(activity, "OnStopActivity", response);
+                this.options.EnrichWithHttpResponse?.Invoke(activity, response);
             }
             catch (Exception ex)
             {
@@ -158,7 +158,7 @@ private void OnException(Activity activity, HttpContext context, Exception excep
 
             try
             {
-                this.options.Enrich?.Invoke(activity, "OnException", exception);
+                this.options.EnrichWithException?.Invoke(activity, exception);
             }
             catch (Exception ex)
             {

src/OpenTelemetry.Instrumentation.AspNet/README.md

@@ -164,35 +164,32 @@ and the `Filter` option does the filtering *before* the Sampler is invoked.
 
 ### Trace Enrich
 
-This option allows one to enrich the activity with additional information from
-the raw `HttpRequest`, `HttpResponse` objects. The `Enrich` action is called
+This instrumentation library provides `EnrichWithHttpRequest`,
+`EnrichWithHttpResponse` and `EnrichWithException` options that can be used to
+enrich the activity with additional information from the raw `HttpRequest`,
+`HttpResponse` and `Exception` objects respectively. These actions are called
 only when `activity.IsAllDataRequested` is `true`. It contains the activity
-itself (which can be enriched), the name of the event, and the actual raw
-object. For event name "OnStartActivity", the actual object will be
-`HttpRequest`. For event name "OnStopActivity", the actual object will be
-`HttpResponse`
+itself (which can be enriched) and the actual raw object.
 
-The following code snippet shows how to add additional tags using `Enrich`.
+The following code snippet shows how to enrich the activity using all 3
+different options.
 
 ```csharp
 this.tracerProvider = Sdk.CreateTracerProviderBuilder()
-    .AddAspNetInstrumentation((options) => options.Enrich
-        = (activity, eventName, rawObject) =>
+    .AddAspNetInstrumentation(o =>
     {
-        if (eventName.Equals("OnStartActivity"))
+        o.EnrichWithHttpRequest = (activity, httpRequest) =>
         {
-            if (rawObject is HttpRequest httpRequest)
-            {
-                activity.SetTag("physicalPath", httpRequest.PhysicalPath);
-            }
-        }
-        else if (eventName.Equals("OnStopActivity"))
+            activity.SetTag("physicalPath", httpRequest.PhysicalPath);
+        };
+        o.EnrichWithHttpResponse = (activity, httpResponse) =>
         {
-            if (rawObject is HttpResponse httpResponse)
-            {
-                activity.SetTag("responseType", httpResponse.ContentType);
-            }
-        }
+            activity.SetTag("responseType", httpResponse.ContentType);
+        };
+        o.EnrichWithException = (activity, exception) =>
+        {
+            activity.SetTag("exceptionType", exception.GetType().ToString());
+        };
     })
     .Build();
 ```