feat: Move OTEL hooks to the SDK

Directory.Packages.props

@@ -16,6 +16,7 @@
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="$(MicrosoftExtensionsVersion)" />
     <PackageVersion Include="Microsoft.Extensions.Options" Version="$(MicrosoftExtensionsVersion)" />
     <PackageVersion Include="System.Collections.Immutable" Version="$(MicrosoftExtensionsVersion)" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="$(MicrosoftExtensionsVersion)" />
     <PackageVersion Include="System.Threading.Channels" Version="$(MicrosoftExtensionsVersion)" />
     <PackageVersion Include="System.ValueTuple" Version="4.6.1" />
   </ItemGroup>
@@ -29,6 +30,8 @@
     <PackageVersion Include="Microsoft.Extensions.Diagnostics.Testing" Version="9.3.0" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
     <PackageVersion Include="NSubstitute" Version="5.3.0" />
+    <PackageVersion Include="OpenTelemetry" Version="1.11.2" />
+    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.11.2" />
     <PackageVersion Include="Reqnroll.xUnit" Version="2.4.1" />
     <PackageVersion Include="xunit" Version="2.9.3" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
@@ -39,4 +42,4 @@
     <PackageVersion Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.3" />
   </ItemGroup>
 
-</Project>
+</Project>

README.md

@@ -79,23 +79,23 @@ public async Task Example()
 
 The [`samples/`](./samples) folder contains example applications demonstrating how to use OpenFeature in different .NET scenarios.
 
-| Sample Name                                       | Description                                                    |
-|---------------------------------------------------|----------------------------------------------------------------|
-| [AspNetCore](/samples/AspNetCore/README.md)       | Feature flags in an ASP.NET Core Web API.                      |
+| Sample Name                                 | Description                               |
+| ------------------------------------------- | ----------------------------------------- |
+| [AspNetCore](/samples/AspNetCore/README.md) | Feature flags in an ASP.NET Core Web API. |
 
 **Getting Started with a Sample:**
 
 1. Navigate to the sample directory
 
-   ```shell
-   cd samples/AspNetCore
-   ```
+    ```shell
+    cd samples/AspNetCore
+    ```
 
 2. Restore dependencies and run
 
-   ```shell
-   dotnet run
-   ```
+    ```shell
+    dotnet run
+    ```
 
 Want to contribute a new sample? See our [CONTRIBUTING](CONTRIBUTING.md) guide!
 
@@ -534,6 +534,135 @@ services.AddOpenFeature(builder =>
 });
 ```
 
+### Trace Enricher Hook
+
+The `TraceEnricherHook` enriches telemetry traces with additional information during the feature flag evaluation lifecycle. This hook adds relevant flag evaluation details as tags and events to the current `Activity` for tracing purposes.
+
+For this hook to function correctly, an active span must be set in the current `Activity`, otherwise the hook will no-op.
+
+Below are the tags added to the trace event:
+
+| Tag Name                    | Description                                                                  | Source                        |
+| --------------------------- | ---------------------------------------------------------------------------- | ----------------------------- |
+| feature_flag.key            | The lookup key of the feature flag                                           | Hook context flag key         |
+| feature_flag.provider.name  | The name of the feature flag provider                                        | Provider metadata             |
+| feature_flag.result.reason  | The reason code which shows how a feature flag value was determined          | Evaluation details            |
+| feature_flag.result.variant | A semantic identifier for an evaluated flag value                            | Evaluation details            |
+| feature_flag.result.value   | The evaluated value of the feature flag                                      | Evaluation details            |
+| feature_flag.context.id     | The unique identifier for the flag evaluation context                        | Flag metadata (if available)  |
+| feature_flag.set.id         | The identifier of the flag set to which the feature flag belongs             | Flag metadata (if available)  |
+| feature_flag.version        | The version of the ruleset used during the evaluation                        | Flag metadata (if available)  |
+| error.type                  | Describes a class of error the operation ended with                          | Evaluation details (if error) |
+| error.message               | A message explaining the nature of an error occurring during flag evaluation | Evaluation details (if error) |
+
+#### Example
+
+The following example demonstrates the use of the `TraceEnricherHook` with the `OpenFeature dotnet-sdk`. The traces are sent to a `jaeger` OTLP collector running at `localhost:4317`.
+
+```csharp
+using OpenFeature.Contrib.Providers.Flagd;
+using OpenFeature.Hooks;
+using OpenTelemetry.Exporter;
+using OpenTelemetry.Resources;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+namespace OpenFeatureTestApp
+{
+    class Hello {
+        static void Main(string[] args) {
+
+            // set up the OpenTelemetry OTLP exporter
+            var tracerProvider = Sdk.CreateTracerProviderBuilder()
+                    .AddSource("my-tracer")
+                    .ConfigureResource(r => r.AddService("jaeger-test"))
+                    .AddOtlpExporter(o =>
+                    {
+                        o.ExportProcessorType = ExportProcessorType.Simple;
+                    })
+                    .Build();
+
+            // add the TraceEnricherHook to the OpenFeature instance
+            OpenFeature.Api.Instance.AddHooks(new TraceEnricherHook());
+
+            var flagdProvider = new FlagdProvider(new Uri("http://localhost:8013"));
+
+            // Set the flagdProvider as the provider for the OpenFeature SDK
+            OpenFeature.Api.Instance.SetProvider(flagdProvider);
+
+            var client = OpenFeature.Api.Instance.GetClient("my-app");
+
+            var val = client.GetBooleanValueAsync("myBoolFlag", false, null);
+
+            // Print the value of the 'myBoolFlag' feature flag
+            System.Console.WriteLine(val.Result.ToString());
+        }
+    }
+}
+```
+
+After running this example, you will be able to see the traces, including the events sent by the hook in your Jaeger UI.
+
+### Metrics Hook
+
+For this hook to function correctly a global `MeterProvider` must be set.
+`MetricsHook` performs metric collection by tapping into various hook stages.
+
+Below are the metrics extracted by this hook and dimensions they carry:
+
+| Metric key                             | Description                     | Unit         | Dimensions                    |
+| -------------------------------------- | ------------------------------- | ------------ | ----------------------------- |
+| feature_flag.evaluation_requests_total | Number of evaluation requests   | {request}    | key, provider name            |
+| feature_flag.evaluation_success_total  | Flag evaluation successes       | {impression} | key, provider name, reason    |
+| feature_flag.evaluation_error_total    | Flag evaluation errors          | 1            | key, provider name, exception |
+| feature_flag.evaluation_active_count   | Active flag evaluations counter | 1            | key, provider name            |
+
+Consider the following code example for usage.
+
+#### Example
+
+The following example demonstrates the use of the `MetricsHook` with the `OpenFeature dotnet-sdk`. The metrics are sent to the `console`.
+
+```csharp
+using OpenFeature.Contrib.Providers.Flagd;
+using OpenFeature;
+using OpenFeature.Hooks;
+using OpenTelemetry;
+using OpenTelemetry.Metrics;
+
+namespace OpenFeatureTestApp
+{
+    class Hello {
+        static void Main(string[] args) {
+
+            // set up the OpenTelemetry OTLP exporter
+            var meterProvider = Sdk.CreateMeterProviderBuilder()
+                    .AddMeter("OpenFeature")
+                    .ConfigureResource(r => r.AddService("openfeature-test"))
+                    .AddConsoleExporter()
+                    .Build();
+
+            // add the MetricsHook to the OpenFeature instance
+            OpenFeature.Api.Instance.AddHooks(new MetricsHook());
+
+            var flagdProvider = new FlagdProvider(new Uri("http://localhost:8013"));
+
+            // Set the flagdProvider as the provider for the OpenFeature SDK
+            OpenFeature.Api.Instance.SetProvider(flagdProvider);
+
+            var client = OpenFeature.Api.Instance.GetClient("my-app");
+
+            var val = client.GetBooleanValueAsync("myBoolFlag", false, null);
+
+            // Print the value of the 'myBoolFlag' feature flag
+            System.Console.WriteLine(val.Result.ToString());
+        }
+    }
+}
+```
+
+After running this example, you should be able to see some metrics being generated into the console.
+
 <!-- x-hide-in-docs-start -->
 
 ## ⭐️ Support the project

samples/AspNetCore/Program.cs

@@ -3,16 +3,33 @@
 using OpenFeature.DependencyInjection.Providers.Memory;
 using OpenFeature.Hooks;
 using OpenFeature.Providers.Memory;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
 
 var builder = WebApplication.CreateBuilder(args);
 
 // Add services to the container.
 builder.Services.AddProblemDetails();
 
+// Configure OpenTelemetry
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(resource => resource.AddService("openfeature-aspnetcore-sample"))
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation()
+        .AddOtlpExporter())
+    .WithMetrics(metrics => metrics
+        .AddAspNetCoreInstrumentation()
+        .AddMeter("OpenFeature")
+        .AddOtlpExporter());
+
 builder.Services.AddOpenFeature(featureBuilder =>
 {
     featureBuilder.AddHostedFeatureLifecycle()
         .AddHook(sp => new LoggingHook(sp.GetRequiredService<ILogger<LoggingHook>>()))
+        .AddHook<MetricsHook>()
+        .AddHook<TraceEnricherHook>()
         .AddInMemoryProvider("InMemory", _ => new Dictionary<string, Flag>()
         {
             {

samples/AspNetCore/Samples.AspNetCore.csproj

@@ -1,9 +1,19 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
 
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\..\src\OpenFeature.DependencyInjection\OpenFeature.DependencyInjection.csproj" />
     <ProjectReference Include="..\..\src\OpenFeature.Hosting\OpenFeature.Hosting.csproj" />
     <ProjectReference Include="..\..\src\OpenFeature\OpenFeature.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
+  </ItemGroup>
+
 </Project>

src/OpenFeature/Hooks/MetricsConstants.cs

@@ -0,0 +1,16 @@
+namespace OpenFeature.Hooks;
+
+internal static class MetricsConstants
+{
+    internal const string ActiveCountName = "feature_flag.evaluation_active_count";
+    internal const string RequestsTotalName = "feature_flag.evaluation_requests_total";
+    internal const string SuccessTotalName = "feature_flag.evaluation_success_total";
+    internal const string ErrorTotalName = "feature_flag.evaluation_error_total";
+
+    internal const string ActiveDescription = "active flag evaluations counter";
+    internal const string RequestsDescription = "feature flag evaluation request counter";
+    internal const string SuccessDescription = "feature flag evaluation success counter";
+    internal const string ErrorDescription = "feature flag evaluation error counter";
+
+    internal const string ExceptionAttr = "exception";
+}

src/OpenFeature/Hooks/MetricsHook.cs

@@ -0,0 +1,100 @@
+using System.Diagnostics;
+using System.Diagnostics.Metrics;
+using System.Reflection;
+using OpenFeature.Constant;
+using OpenFeature.Model;
+using OpenFeature.Telemetry;
+
+namespace OpenFeature.Hooks;
+
+/// <summary>
+/// Represents a hook for capturing metrics related to flag evaluations.
+/// The meter instrumentation name is "OpenFeature".
+/// </summary>
+/// <remarks> This is still experimental and subject to change. </remarks>
+public class MetricsHook : Hook
+{
+    private static readonly AssemblyName AssemblyName = typeof(MetricsHook).Assembly.GetName();
+    private static readonly string InstrumentationName = AssemblyName.Name ?? "OpenFeature";
+    private static readonly string InstrumentationVersion = AssemblyName.Version?.ToString() ?? "1.0.0";
+    private static readonly Meter Meter = new(InstrumentationName, InstrumentationVersion);
+
+    private readonly UpDownCounter<long> _evaluationActiveUpDownCounter;
+    private readonly Counter<long> _evaluationRequestCounter;
+    private readonly Counter<long> _evaluationSuccessCounter;
+    private readonly Counter<long> _evaluationErrorCounter;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MetricsHook"/> class.
+    /// </summary>
+    public MetricsHook()
+    {
+        this._evaluationActiveUpDownCounter = Meter.CreateUpDownCounter<long>(MetricsConstants.ActiveCountName, description: MetricsConstants.ActiveDescription);
+        this._evaluationRequestCounter = Meter.CreateCounter<long>(MetricsConstants.RequestsTotalName, "{request}", MetricsConstants.RequestsDescription);
+        this._evaluationSuccessCounter = Meter.CreateCounter<long>(MetricsConstants.SuccessTotalName, "{impression}", MetricsConstants.SuccessDescription);
+        this._evaluationErrorCounter = Meter.CreateCounter<long>(MetricsConstants.ErrorTotalName, description: MetricsConstants.ErrorDescription);
+    }
+
+    /// <inheritdoc/>
+    public override ValueTask<EvaluationContext> BeforeAsync<T>(HookContext<T> context, IReadOnlyDictionary<string, object>? hints = null, CancellationToken cancellationToken = default)
+    {
+        var tagList = new TagList
+        {
+            { TelemetryConstants.Key, context.FlagKey },
+            { TelemetryConstants.Provider, context.ProviderMetadata.Name }
+        };
+
+        this._evaluationActiveUpDownCounter.Add(1, tagList);
+        this._evaluationRequestCounter.Add(1, tagList);
+
+        return base.BeforeAsync(context, hints, cancellationToken);
+    }
+
+
+    /// <inheritdoc/>
+    public override ValueTask AfterAsync<T>(HookContext<T> context, FlagEvaluationDetails<T> details, IReadOnlyDictionary<string, object>? hints = null, CancellationToken cancellationToken = default)
+    {
+        var tagList = new TagList
+        {
+            { TelemetryConstants.Key, context.FlagKey },
+            { TelemetryConstants.Provider, context.ProviderMetadata.Name },
+            { TelemetryConstants.Reason, details.Reason ?? Reason.Unknown.ToString() }
+        };
+
+        this._evaluationSuccessCounter.Add(1, tagList);
+
+        return base.AfterAsync(context, details, hints, cancellationToken);
+    }
+
+    /// <inheritdoc/>
+    public override ValueTask ErrorAsync<T>(HookContext<T> context, Exception error, IReadOnlyDictionary<string, object>? hints = null, CancellationToken cancellationToken = default)
+    {
+        var tagList = new TagList
+        {
+            { TelemetryConstants.Key, context.FlagKey },
+            { TelemetryConstants.Provider, context.ProviderMetadata.Name },
+            { MetricsConstants.ExceptionAttr, error.Message }
+        };
+
+        this._evaluationErrorCounter.Add(1, tagList);
+
+        return base.ErrorAsync(context, error, hints, cancellationToken);
+    }
+
+    /// <inheritdoc/>
+    public override ValueTask FinallyAsync<T>(HookContext<T> context,
+        FlagEvaluationDetails<T> evaluationDetails,
+        IReadOnlyDictionary<string, object>? hints = null,
+        CancellationToken cancellationToken = default)
+    {
+        var tagList = new TagList
+        {
+            { TelemetryConstants.Key, context.FlagKey },
+            { TelemetryConstants.Provider, context.ProviderMetadata.Name }
+        };
+
+        this._evaluationActiveUpDownCounter.Add(-1, tagList);
+
+        return base.FinallyAsync(context, evaluationDetails, hints, cancellationToken);
+    }
+}