feat: Move OTEL hooks to the SDK (#338)

<!-- Please use this template for your pull request. -->
<!-- Please use the sections that you need and delete other sections -->

## Move OTEL hooks to the SDK
<!-- add the description of the PR here -->

This pull request introduces telemetry enhancements to the OpenFeature
.NET SDK by adding new hooks for tracing and metrics, updating
dependencies, and providing examples and tests. The most significant
changes include the addition of the `TraceEnricherHook` and
`MetricsHook` classes, integration of OpenTelemetry in the ASP.NET Core
sample, and updates to dependencies to support telemetry features.

### Telemetry Enhancements

* **Trace Enricher Hook**: Added `TraceEnricherHook` to enrich telemetry
traces with feature flag evaluation details, including tags and events
for tracing purposes. This hook integrates with the current `Activity`
and supports error handling.
* **Metrics Hook**: Introduced `MetricsHook` for capturing metrics such
as evaluation requests, successes, errors, and active evaluations.
Metrics are collected using OpenTelemetry's `Meter` API.
[[1]](diffhunk://#diff-912b71a06f9a65012af403b04269f68f3cb9ee580d0dd62e1d6afc99bd433d31R1-R100)
[[2]](diffhunk://#diff-9c7590e55694b19483ea6d802e6a1bb34418366a8f66d6f35b57ae81adb5bf17R1-R16)

### Dependency Updates

* **OpenTelemetry Dependencies**: Added
`OpenTelemetry.Extensions.Hosting`,
`OpenTelemetry.Instrumentation.AspNetCore`, and
`OpenTelemetry.Exporter.OpenTelemetryProtocol` to the ASP.NET Core
sample project to support telemetry features.
[[1]](diffhunk://#diff-40299025547d304b834a53acda1eb9a8a6f49f2ec679b6bcebd3449211497c56R3-R18)
[[2]](diffhunk://#diff-711ea17cbdebe419375c7684c8c39a1423d2bebcf8976ddd7bdd78deaab65b21R12)
* **DiagnosticSource Dependency**: Included
`System.Diagnostics.DiagnosticSource` in the main project and
centralized dependency management.
[[1]](diffhunk://#diff-5baf5f9e448ad54ab25a091adee0da05d4d228481c9200518fcb1b53a65d4156R19)
[[2]](diffhunk://#diff-5baf5f9e448ad54ab25a091adee0da05d4d228481c9200518fcb1b53a65d4156R33-R34)

### Documentation and Examples

* **README Updates**: Added documentation for `TraceEnricherHook` and
`MetricsHook`, including detailed descriptions, examples, and usage
instructions for integrating these hooks with OpenTelemetry.
* **ASP.NET Core Sample**: Updated the sample application to demonstrate
the use of `TraceEnricherHook` and `MetricsHook` with OpenTelemetry
tracing and metrics.
[[1]](diffhunk://#diff-41550b31d77b5898b38a3280f8ffbc5d2531fc4d4884079ebf3c5e953a85075dR6-R32)
[[2]](diffhunk://#diff-40299025547d304b834a53acda1eb9a8a6f49f2ec679b6bcebd3449211497c56R3-R18)

### Testing

* **MetricsHook Tests**: Added unit tests for `MetricsHook` to verify
metrics collection during different stages of feature flag evaluation
(e.g., `BeforeAsync`, `AfterAsync`, `ErrorAsync`, `FinallyAsync`).
### Related Issues
<!-- add here the GitHub issue that this PR resolves if applicable -->

Fixes #175 

### Notes
* In this PR I made some changes to the `samples` application. This
allow us to see the metrics and traces in any OTEL tool.

Check the screenshots below:

![Screenshot 2025-06-25 at 18 58
59](https://github.com/user-attachments/assets/c5ce5e1d-6506-4e4b-a95c-707e65a1d5f6)

### Follow-up Tasks
<!-- anything that is related to this PR but not done here should be
noted under this section -->
<!-- If there is a need for a new issue, please link it here -->
- We should remove any reference in the other repository and mark the
Nuget package as deprecated.

---------

Signed-off-by: André Silva <[email protected]>

Author: askpt

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);
+    }
+}