EnrichmentScope & EnrichingActivityProcessor

OpenTelemetry.sln

@@ -202,6 +202,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "building-your-own-exporter"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "building-your-own-sampler", "docs\trace\building-your-own-sampler\building-your-own-sampler.csproj", "{D6318071-BE9F-43AF-9F28-A38894238627}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "enriching-activity-processor", "docs\trace\enriching-activity-processor\enriching-activity-processor.csproj", "{89EA1013-6E8D-4A69-9D8B-D3FBA0355726}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -380,6 +382,10 @@ Global
 		{D6318071-BE9F-43AF-9F28-A38894238627}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{D6318071-BE9F-43AF-9F28-A38894238627}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{D6318071-BE9F-43AF-9F28-A38894238627}.Release|Any CPU.Build.0 = Release|Any CPU
+		{89EA1013-6E8D-4A69-9D8B-D3FBA0355726}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{89EA1013-6E8D-4A69-9D8B-D3FBA0355726}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{89EA1013-6E8D-4A69-9D8B-D3FBA0355726}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{89EA1013-6E8D-4A69-9D8B-D3FBA0355726}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -408,6 +414,7 @@ Global
 		{CB401DF1-FF5C-4055-886E-1183E832B2D6} = {7CB2F02E-03FA-4FFF-89A5-C51F107623FD}
 		{9574368D-1230-4334-AA5D-EC2C2F47AA43} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}
 		{D6318071-BE9F-43AF-9F28-A38894238627} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}
+		{89EA1013-6E8D-4A69-9D8B-D3FBA0355726} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521}

docs/trace/enriching-activity-processor/Program.cs

@@ -0,0 +1,67 @@
+// <copyright file="Program.cs" company="OpenTelemetry Authors">
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using System.Net.Http;
+using System.Threading.Tasks;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+public class Program
+{
+    private static readonly HttpClient HttpClient = new HttpClient();
+
+    public static async Task Main()
+    {
+        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+            .AddHttpClientInstrumentation()
+            .AddProcessor(new EnrichingActivityProcessor())
+            .AddConsoleExporter()
+            .Build();
+
+        using (EnrichmentScope.Begin(a =>
+        {
+            a.AddTag("mycompany.user_id", 1234);
+            a.AddTag("mycompany.customer_id", 5678);
+
+            HttpRequestMessage request = (HttpRequestMessage)a.GetCustomProperty("HttpHandler.Request");
+            if (request != null)
+            {
+                a.AddTag("http.user_agent", request.Headers.UserAgent.ToString());
+            }
+
+            HttpResponseMessage response = (HttpResponseMessage)a.GetCustomProperty("HttpHandler.Response");
+            if (response != null)
+            {
+                a.AddTag("http.content_type", response.Content.Headers.ContentType.ToString());
+            }
+        }))
+        {
+            using var request = new HttpRequestMessage
+            {
+                Method = HttpMethod.Get,
+                RequestUri = new Uri("https://www.opentelemetry.io/"),
+            };
+
+            request.Headers.UserAgent.TryParseAdd("mycompany/mylibrary");
+
+            using var response = await HttpClient.SendAsync(request).ConfigureAwait(false);
+        }
+
+        Console.WriteLine("Press any key to exit.");
+        Console.ReadKey();
+    }
+}

docs/trace/enriching-activity-processor/README.md

@@ -0,0 +1,113 @@
+# EnrichingActivityProcessor
+
+Sometimes the built-in instrumentation doesn't add enough data or you want to
+augment the data it provides with contextual information your application or
+library has available. For these cases OpenTelemetry .NET provides an
+`EnrichingActivityProcessor` and `EnrichmentScope` API.
+
+1. To enrich your spans first add the `EnrichingActivityProcessor` to your
+   `TracerProvider`:
+
+    ```csharp
+    using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+        .AddHttpClientInstrumentation()
+        .AddProcessor(new EnrichingActivityProcessor())
+        .AddConsoleExporter()
+        .Build();
+    ```
+
+    **Note:** Order is important. Make sure your `EnrichingActivityProcessor` is
+    registered before your `Exporter` and any other `ActivityProcessor`s you are
+    using.
+
+2. Use `EnrichmentScope.Begin` to wrap the call you want to instrument:
+
+    ```csharp
+    using (EnrichmentScope.Begin(a =>
+    {
+        a.AddTag("mycompany.user_id", 1234);
+        a.AddTag("mycompany.customer_id", 5678);
+
+        HttpRequestMessage request = (HttpRequestMessage)a.GetCustomProperty("HttpHandler.Request");
+        if (request != null)
+        {
+            a.AddTag("http.user_agent", request.Headers.UserAgent.ToString());
+        }
+
+        HttpResponseMessage response = (HttpResponseMessage)a.GetCustomProperty("HttpHandler.Response");
+        if (response != null)
+        {
+            a.AddTag("http.content_type", response.Content.Headers.ContentType.ToString());
+        }
+    }))
+    {
+        using var request = new HttpRequestMessage
+        {
+            Method = HttpMethod.Get,
+            RequestUri = new Uri("https://www.opentelemetry.io/"),
+        };
+
+        request.Headers.UserAgent.TryParseAdd("mycompany/mylibrary");
+
+        using var response = await HttpClient.SendAsync(request).ConfigureAwait(false);
+    }
+    ```
+
+    In that example the span created for the call to `www.opentelemetry.io` will
+    be decorated with `mycompany.user_id` & `mycompany.customer_id` tags
+    (simulating contextual data) and `http.user_agent` & `http.content_type`
+    tags which are taken directly from the raw HTTP objects.
+
+## Advanced Usage
+
+### EnrichmentScopeTarget
+
+`EnrichmentScope.Begin` supports a "target" argument which can be used to alter
+the enrichment behavior via the `EnrichmentScopeTarget` enumeration:
+
+```csharp
+using EnrichmentScope.Begin(
+    target: EnrichmentScopeTarget.FirstChild,
+    enrichmentAction: a => a.AddTag("mycompany.user_id", 1234));
+
+using EnrichmentScope.Begin(
+    target: EnrichmentScopeTarget.AllChildren,
+    enrichmentAction: a => a.AddTag("mycompany.user_id", 1234));
+```
+
+The default behavior is `EnrichmentScopeTarget.FirstChild`.
+
+| Name | Description |
+| ---- | ----------- |
+| FirstChild  | The first child `Activity` created under the scope will be enriched and then the scope will automatically be closed. |
+| AllChildren | All child `Activity` objects created under the scope will be enriched until the scope is closed. |
+
+### Nesting
+
+Enrichment scopes may be nested.
+
+```csharp
+using EnrichmentScope.Begin(
+    target: EnrichmentScopeTarget.AllChildren,
+    enrichmentAction: a => a.AddTag("mycompany.customer_id", 5678))
+{
+    using EnrichmentScope.Begin(
+        target: EnrichmentScopeTarget.FirstChild,
+        enrichmentAction: a => a.AddTag("mycompany.user_id", 1234))
+    {
+        using var response1 = await HttpClient.GetAsync("https://www.opentelemetry.io/").ConfigureAwait(false);
+    }
+
+    using EnrichmentScope.Begin(
+        target: EnrichmentScopeTarget.FirstChild,
+        enrichmentAction: a => a.AddTag("mycompany.user_id", 1818))
+    {
+        using var response2 = await HttpClient.GetAsync("https://www.cncf.io/").ConfigureAwait(false);
+    }
+}
+```
+
+In that example the request to `www.opentelemetry.io` will be enriched with the
+`mycompany.user_id=1234` and `mycompany.customer_id=5678` tags (in that order)
+and the request to `www.cncf.com` will be enriched with the
+`mycompany.user_id=1818` and `mycompany.customer_id=5678` tags (in that order).

docs/trace/enriching-activity-processor/enriching-activity-processor.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <!---
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="$(OpenTelemetryExporterConsolePkgVer)" />
+    -->
+    <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Exporter.Console\OpenTelemetry.Exporter.Console.csproj" />
+    <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Instrumentation.Http\OpenTelemetry.Instrumentation.Http.csproj" />
+  </ItemGroup>
+</Project>

src/OpenTelemetry.Instrumentation.Http/Implementation/HttpHandlerDiagnosticListener.cs

@@ -90,6 +90,7 @@ public override void OnStartActivity(Activity activity, object payload)
 
             activity.SetKind(ActivityKind.Client);
             activity.DisplayName = HttpTagHelper.GetOperationNameForHttpMethod(request.Method);
+            activity.SetCustomProperty("HttpHandler.Request", request);
 
             this.activitySource.Start(activity);
 
@@ -135,7 +136,8 @@ public override void OnStopActivity(Activity activity, object payload)
 
                 if (this.stopResponseFetcher.Fetch(payload) is HttpResponseMessage response)
                 {
-                    // response could be null for DNS issues, timeouts, etc...
+                    activity.SetCustomProperty("HttpHandler.Response", response);
+
                     activity.SetTag(SemanticConventions.AttributeHttpStatusCode, (int)response.StatusCode);
 
                     activity.SetStatus(
@@ -158,6 +160,8 @@ public override void OnException(Activity activity, object payload)
                     return;
                 }
 
+                activity.SetCustomProperty("HttpHandler.Exception", exc);
+
                 if (exc is HttpRequestException)
                 {
                     if (exc.InnerException is SocketException exception)

src/OpenTelemetry/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+* Added EnrichmentScope & EnrichingActivityProcessor
+  ([#969](https://github.com/open-telemetry/opentelemetry-dotnet/pull/969))
 * Modified Sampler implementation to match the spec
   ([#1037](https://github.com/open-telemetry/opentelemetry-dotnet/pull/1037))
 * Changed `ActivityProcessor` to implement `IDisposable`

src/OpenTelemetry/Trace/EnrichingActivityProcessor.cs

@@ -0,0 +1,54 @@
+// <copyright file="EnrichingActivityProcessor.cs" company="OpenTelemetry Authors">
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using System.Diagnostics;
+using OpenTelemetry.Internal;
+
+namespace OpenTelemetry.Trace
+{
+    /// <summary>
+    /// An <see cref="ActivityProcessor"/> implementation that enriches <see cref="Activity"/> objects using <see cref="EnrichmentScope"/>s.
+    /// </summary>
+    public class EnrichingActivityProcessor : ActivityProcessor
+    {
+        /// <inheritdoc/>
+        public override void OnEnd(Activity activity)
+        {
+            EnrichmentScope scope = EnrichmentScope.Current;
+            while (scope != null)
+            {
+                try
+                {
+                    scope.EnrichmentAction?.Invoke(activity);
+                }
+                catch (Exception ex)
+                {
+                    OpenTelemetrySdkEventSource.Log.SpanProcessorException(nameof(EnrichingActivityProcessor), ex);
+                }
+
+                var nextParent = scope.Parent;
+
+                if (scope.EnrichmentTarget == EnrichmentScopeTarget.FirstChild)
+                {
+                    scope.Dispose();
+                }
+
+                scope = nextParent;
+            }
+        }
+    }
+}