feat: Add OTEL compatible telemetry object builder (#397)

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

## This PR

This pull request introduces a feature for generating telemetry events
to track feature flag evaluations. It adds a new `EvaluationEvent`
class, a builder for creating these events, constants for telemetry
attributes, and metadata definitions. It also includes comprehensive
unit tests to ensure the correctness of the implementation.

### New Feature: Telemetry Event Generation

* **`EvaluationEvent` class**: Added a new class to represent evaluation
events for feature flags, including properties for the event name and
attributes. (`src/OpenFeature/Telemetry/EvaluationEvent.cs`)
* **`EvaluationEventBuilder` class**: Introduced a static builder class
to construct `EvaluationEvent` instances using flag evaluation details
and hook context.
(`src/OpenFeature/Telemetry/EvaluationEventBuilder.cs`)

### Supporting Components

* **Telemetry constants**: Defined a set of constants in
`TelemetryConstants` to standardize attribute keys for
OpenTelemetry-compliant feature flag events.
(`src/OpenFeature/Telemetry/TelemetryConstants.cs`)
* **Flag metadata attributes**: Added `TelemetryFlagMetadata` to define
well-known metadata attributes for telemetry events, such as
`contextId`, `flagSetId`, and `version`.
(`src/OpenFeature/Telemetry/TelemetryFlagMetadata.cs`)

### Unit Tests

* **`EvaluationEventBuilderTests`**: Added unit tests to validate the
behavior of `EvaluationEventBuilder`, including scenarios for handling
errors, missing metadata, and missing attributes.
(`test/OpenFeature.Tests/Telemetry/EvaluationEventBuilderTests.cs`)

### Related Issues
<!-- add here the GitHub issue that this PR resolves if applicable -->

Fixes #381

---------

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

Author: askpt

src/OpenFeature/Telemetry/EvaluationEvent.cs

@@ -0,0 +1,30 @@
+using System.Collections.Generic;
+
+namespace OpenFeature.Telemetry;
+
+/// <summary>
+/// Represents an evaluation event for feature flags.
+/// </summary>
+public class EvaluationEvent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EvaluationEvent"/> class.
+    /// </summary>
+    /// <param name="name">The name of the event.</param>
+    /// <param name="attributes">The attributes of the event.</param>
+    public EvaluationEvent(string name, IDictionary<string, object?> attributes)
+    {
+        Name = name;
+        Attributes = new Dictionary<string, object?>(attributes);
+    }
+
+    /// <summary>
+    /// Gets the name of the event.
+    /// </summary>
+    public string Name { get; }
+
+    /// <summary>
+    /// Gets the attributes of the event.
+    /// </summary>
+    public IReadOnlyDictionary<string, object?> Attributes { get; }
+}

src/OpenFeature/Telemetry/EvaluationEventBuilder.cs

@@ -0,0 +1,58 @@
+using System.Collections.Generic;
+using OpenFeature.Constant;
+using OpenFeature.Model;
+
+namespace OpenFeature.Telemetry;
+
+/// <summary>
+/// Class for creating evaluation events for feature flags.
+/// </summary>
+public sealed class EvaluationEventBuilder
+{
+    private const string EventName = "feature_flag.evaluation";
+
+    /// <summary>
+    /// Gets the default instance of the <see cref="EvaluationEventBuilder"/>.
+    /// </summary>
+    public static EvaluationEventBuilder Default { get; } = new();
+
+    /// <summary>
+    /// Creates an evaluation event based on the provided hook context and flag evaluation details.
+    /// </summary>
+    /// <param name="hookContext">The context of the hook containing flag key and provider metadata.</param>
+    /// <param name="details">The details of the flag evaluation including reason, variant, and metadata.</param>
+    /// <returns>An instance of <see cref="EvaluationEvent"/> containing the event name, attributes, and body.</returns>
+    public EvaluationEvent Build(HookContext<Value> hookContext, FlagEvaluationDetails<Value> details)
+    {
+        var attributes = new Dictionary<string, object?>
+        {
+            { TelemetryConstants.Key, hookContext.FlagKey },
+            { TelemetryConstants.Provider, hookContext.ProviderMetadata.Name }
+        };
+
+        attributes[TelemetryConstants.Reason] = !string.IsNullOrWhiteSpace(details.Reason)
+            ? details.Reason?.ToLowerInvariant()
+            : Reason.Unknown.ToLowerInvariant();
+        attributes[TelemetryConstants.Variant] = details.Variant;
+        attributes[TelemetryConstants.Value] = details.Value;
+
+        if (details.FlagMetadata != null)
+        {
+            attributes[TelemetryConstants.ContextId] = details.FlagMetadata.GetString(TelemetryFlagMetadata.ContextId);
+            attributes[TelemetryConstants.FlagSetId] = details.FlagMetadata.GetString(TelemetryFlagMetadata.FlagSetId);
+            attributes[TelemetryConstants.Version] = details.FlagMetadata.GetString(TelemetryFlagMetadata.Version);
+        }
+
+        if (details.ErrorType != ErrorType.None)
+        {
+            attributes[TelemetryConstants.ErrorCode] = details.ErrorType.ToString().ToLowerInvariant();
+
+            if (!string.IsNullOrWhiteSpace(details.ErrorMessage))
+            {
+                attributes[TelemetryConstants.ErrorMessage] = details.ErrorMessage;
+            }
+        }
+
+        return new EvaluationEvent(EventName, attributes);
+    }
+}

src/OpenFeature/Telemetry/TelemetryConstants.cs

@@ -0,0 +1,59 @@
+namespace OpenFeature.Telemetry;
+
+/// <summary>
+/// The attributes of an OpenTelemetry compliant event for flag evaluation.
+/// <see href="https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/"/>
+/// </summary>
+public static class TelemetryConstants
+{
+    /// <summary>
+    /// The lookup key of the feature flag.
+    /// </summary>
+    public const string Key = "feature_flag.key";
+
+    /// <summary>
+    /// Describes a class of error the operation ended with.
+    /// </summary>
+    public const string ErrorCode = "error.type";
+
+    /// <summary>
+    /// A message explaining the nature of an error occurring during flag evaluation.
+    /// </summary>
+    public const string ErrorMessage = "error.message";
+
+    /// <summary>
+    /// A semantic identifier for an evaluated flag value.
+    /// </summary>
+    public const string Variant = "feature_flag.result.variant";
+
+    /// <summary>
+    /// The evaluated value of the feature flag.
+    /// </summary>
+    public const string Value = "feature_flag.result.value";
+
+    /// <summary>
+    /// The unique identifier for the flag evaluation context. For example, the targeting key.
+    /// </summary>
+    public const string ContextId = "feature_flag.context.id";
+
+    /// <summary>
+    /// The reason code which shows how a feature flag value was determined.
+    /// </summary>
+    public const string Reason = "feature_flag.result.reason";
+
+    /// <summary>
+    /// Describes a class of error the operation ended with.
+    /// </summary>
+    public const string Provider = "feature_flag.provider.name";
+
+    /// <summary>
+    /// The identifier of the flag set to which the feature flag belongs.
+    /// </summary>
+    public const string FlagSetId = "feature_flag.set.id";
+
+    /// <summary>
+    /// The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset.
+    /// </summary>
+    public const string Version = "feature_flag.version";
+
+}

src/OpenFeature/Telemetry/TelemetryFlagMetadata.cs

@@ -0,0 +1,25 @@
+namespace OpenFeature.Telemetry;
+
+/// <summary>
+/// Well-known flag metadata attributes for telemetry events.
+/// <remarks>See also: https://openfeature.dev/specification/appendix-d#flag-metadata</remarks>
+/// </summary>
+public static class TelemetryFlagMetadata
+{
+    /// <summary>
+    /// The context identifier returned in the flag metadata uniquely identifies
+    /// the subject of the flag evaluation. If not available, the targeting key
+    /// should be used.
+    /// </summary>
+    public const string ContextId = "contextId";
+
+    /// <summary>
+    /// ///A logical identifier for the flag set.
+    /// </summary>
+    public const string FlagSetId = "flagSetId";
+
+    /// <summary>
+    /// A version string (format unspecified) for the flag or flag set.
+    /// </summary>
+    public const string Version = "version";
+}

test/OpenFeature.Tests/Telemetry/EvaluationEventBuilderTests.cs

@@ -0,0 +1,174 @@
+using System.Collections.Generic;
+using OpenFeature.Constant;
+using OpenFeature.Model;
+using OpenFeature.Telemetry;
+using Xunit;
+
+namespace OpenFeature.Tests.Telemetry;
+
+public class EvaluationEventBuilderTests
+{
+    private readonly EvaluationEventBuilder _builder = EvaluationEventBuilder.Default;
+
+    [Fact]
+    public void Build_ShouldReturnEventWithCorrectAttributes()
+    {
+        // Arrange
+        var clientMetadata = new ClientMetadata("client", "1.0.0");
+        var providerMetadata = new Metadata("provider");
+        var hookContext = new HookContext<Value>("flagKey", new Value(), FlagValueType.Object, clientMetadata,
+            providerMetadata, EvaluationContext.Empty);
+        var metadata = new Dictionary<string, object>
+        {
+            { "flagSetId", "flagSetId" }, { "contextId", "contextId" }, { "version", "version" }
+        };
+        var flagMetadata = new ImmutableMetadata(metadata);
+        var details = new FlagEvaluationDetails<Value>("flagKey", new Value("value"), ErrorType.None,
+            reason: "reason", variant: "variant", flagMetadata: flagMetadata);
+
+        // Act
+        var evaluationEvent = _builder.Build(hookContext, details);
+
+        // Assert
+        Assert.Equal("feature_flag.evaluation", evaluationEvent.Name);
+        Assert.Equal("flagKey", evaluationEvent.Attributes[TelemetryConstants.Key]);
+        Assert.Equal("provider", evaluationEvent.Attributes[TelemetryConstants.Provider]);
+        Assert.Equal("reason", evaluationEvent.Attributes[TelemetryConstants.Reason]);
+        Assert.Equal("variant", evaluationEvent.Attributes[TelemetryConstants.Variant]);
+        Assert.Equal("contextId", evaluationEvent.Attributes[TelemetryConstants.ContextId]);
+        Assert.Equal("flagSetId", evaluationEvent.Attributes[TelemetryConstants.FlagSetId]);
+        Assert.Equal("version", evaluationEvent.Attributes[TelemetryConstants.Version]);
+    }
+
+    [Fact]
+    public void Build_ShouldHandleErrorDetails()
+    {
+        // Arrange
+        var clientMetadata = new ClientMetadata("client", "1.0.0");
+        var providerMetadata = new Metadata("provider");
+        var hookContext = new HookContext<Value>("flagKey", new Value(), FlagValueType.Object, clientMetadata,
+            providerMetadata, EvaluationContext.Empty);
+        var metadata = new Dictionary<string, object>
+        {
+            { "flagSetId", "flagSetId" }, { "contextId", "contextId" }, { "version", "version" }
+        };
+        var flagMetadata = new ImmutableMetadata(metadata);
+        var details = new FlagEvaluationDetails<Value>("flagKey", new Value("value"), ErrorType.General,
+            errorMessage: "errorMessage", reason: "reason", variant: "variant", flagMetadata: flagMetadata);
+
+        // Act
+        var evaluationEvent = _builder.Build(hookContext, details);
+
+        // Assert
+        Assert.Equal("general", evaluationEvent.Attributes[TelemetryConstants.ErrorCode]);
+        Assert.Equal("errorMessage", evaluationEvent.Attributes[TelemetryConstants.ErrorMessage]);
+    }
+
+    [Fact]
+    public void Build_ShouldHandleMissingVariant()
+    {
+        // Arrange
+        var clientMetadata = new ClientMetadata("client", "1.0.0");
+        var providerMetadata = new Metadata("provider");
+        var hookContext = new HookContext<Value>("flagKey", new Value("value"), FlagValueType.Object, clientMetadata,
+            providerMetadata, EvaluationContext.Empty);
+        var metadata = new Dictionary<string, object>
+        {
+            { "flagSetId", "flagSetId" }, { "contextId", "contextId" }, { "version", "version" }
+        };
+        var flagMetadata = new ImmutableMetadata(metadata);
+        var details = new FlagEvaluationDetails<Value>("flagKey", new Value("value"), ErrorType.None,
+            reason: "reason", variant: null, flagMetadata: flagMetadata);
+
+        // Act
+        var evaluationEvent = _builder.Build(hookContext, details);
+
+        // Assert
+        Assert.Null(evaluationEvent.Attributes[TelemetryConstants.Variant]);
+    }
+
+    [Fact]
+    public void Build_ShouldHandleMissingFlagMetadata()
+    {
+        // Arrange
+        var clientMetadata = new ClientMetadata("client", "1.0.0");
+        var providerMetadata = new Metadata("provider");
+        var hookContext = new HookContext<Value>("flagKey", new Value("value"), FlagValueType.Object, clientMetadata,
+            providerMetadata, EvaluationContext.Empty);
+        var flagMetadata = new ImmutableMetadata();
+        var details = new FlagEvaluationDetails<Value>("flagKey", new Value("value"), ErrorType.None,
+            reason: "reason", variant: "", flagMetadata: flagMetadata);
+
+        // Act
+        var evaluationEvent = _builder.Build(hookContext, details);
+
+        // Assert
+        Assert.Null(evaluationEvent.Attributes[TelemetryConstants.ContextId]);
+        Assert.Null(evaluationEvent.Attributes[TelemetryConstants.FlagSetId]);
+        Assert.Null(evaluationEvent.Attributes[TelemetryConstants.Version]);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData(" ")]
+    public void Build_ShouldHandleMissingReason(string? reason)
+    {
+        // Arrange
+        var clientMetadata = new ClientMetadata("client", "1.0.0");
+        var providerMetadata = new Metadata("provider");
+        var hookContext = new HookContext<Value>("flagKey", new Value("value"), FlagValueType.Object, clientMetadata,
+            providerMetadata, EvaluationContext.Empty);
+        var flagMetadata = new ImmutableMetadata();
+        var details = new FlagEvaluationDetails<Value>("flagKey", new Value("value"), ErrorType.None,
+            reason: reason, variant: "", flagMetadata: flagMetadata);
+
+        // Act
+        var evaluationEvent = _builder.Build(hookContext, details);
+
+        // Assert
+        Assert.Equal(Reason.Unknown.ToLowerInvariant(), evaluationEvent.Attributes[TelemetryConstants.Reason]);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData(" ")]
+    public void Build_ShouldHandleErrorWithEmptyErrorMessage(string? errorMessage)
+    {
+        // Arrange
+        var clientMetadata = new ClientMetadata("client", "1.0.0");
+        var providerMetadata = new Metadata("provider");
+        var hookContext = new HookContext<Value>("flagKey", new Value("value"), FlagValueType.Object, clientMetadata,
+            providerMetadata, EvaluationContext.Empty);
+        var flagMetadata = new ImmutableMetadata();
+        var details = new FlagEvaluationDetails<Value>("flagKey", new Value("value"), ErrorType.General,
+            errorMessage: errorMessage, reason: "reason", variant: "", flagMetadata: flagMetadata);
+
+        // Act
+        var evaluationEvent = _builder.Build(hookContext, details);
+
+        // Assert
+        Assert.Equal("general", evaluationEvent.Attributes[TelemetryConstants.ErrorCode]);
+        Assert.False(evaluationEvent.Attributes.ContainsKey(TelemetryConstants.ErrorMessage));
+    }
+
+    [Fact]
+    public void Build_ShouldIncludeValueAttributeInEvent()
+    {
+        // Arrange
+        var clientMetadata = new ClientMetadata("client", "1.0.0");
+        var providerMetadata = new Metadata("provider");
+        var hookContext = new HookContext<Value>("flagKey", new Value(), FlagValueType.Object, clientMetadata,
+            providerMetadata, EvaluationContext.Empty);
+        var testValue = new Value("test-value");
+        var details = new FlagEvaluationDetails<Value>("flagKey", testValue, ErrorType.None,
+            reason: "reason", variant: "variant", flagMetadata: new ImmutableMetadata());
+
+        // Act
+        var evaluationEvent = _builder.Build(hookContext, details);
+
+        // Assert
+        Assert.Equal(testValue, evaluationEvent.Attributes[TelemetryConstants.Value]);
+    }
+}