diff --git a/src/OpenFeature/Telemetry/EvaluationEvent.cs b/src/OpenFeature/Telemetry/EvaluationEvent.cs new file mode 100644 index 00000000..666f7b4c --- /dev/null +++ b/src/OpenFeature/Telemetry/EvaluationEvent.cs @@ -0,0 +1,37 @@ +using System.Collections.Generic; + +namespace OpenFeature.Telemetry; + +/// +/// Represents an evaluation event for feature flags. +/// +public class EvaluationEvent +{ + /// + /// Initializes a new instance of the class. + /// + /// The name of the event. + /// The attributes of the event. + /// The body of the event. + public EvaluationEvent(string name, Dictionary attributes, Dictionary body) + { + this.Name = name; + this.Attributes = attributes; + this.Body = body; + } + + /// + /// Gets or sets the name of the event. + /// + public string Name { get; set; } + + /// + /// Gets or sets the attributes of the event. + /// + public Dictionary Attributes { get; set; } + + /// + /// Gets or sets the body of the event. + /// + public Dictionary Body { get; set; } +} diff --git a/src/OpenFeature/Telemetry/EvaluationEventBuilder.cs b/src/OpenFeature/Telemetry/EvaluationEventBuilder.cs new file mode 100644 index 00000000..4dc17aab --- /dev/null +++ b/src/OpenFeature/Telemetry/EvaluationEventBuilder.cs @@ -0,0 +1,49 @@ +using System.Collections.Generic; +using OpenFeature.Constant; +using OpenFeature.Model; + +namespace OpenFeature.Telemetry; + +/// +/// Class for creating evaluation events for feature flags. +/// +public static class EvaluationEventBuilder +{ + private const string EventName = "feature_flag.evaluation"; + + /// + /// Creates an evaluation event based on the provided hook context and flag evaluation details. + /// + /// The context of the hook containing flag key and provider metadata. + /// The details of the flag evaluation including reason, variant, and metadata. + /// An instance of containing the event name, attributes, and body. + public static EvaluationEvent Build(HookContext hookContext, FlagEvaluationDetails details) + { + var attributes = new Dictionary + { + { TelemetryConstants.Key, hookContext.FlagKey }, + { TelemetryConstants.Provider, hookContext.ProviderMetadata.Name } + }; + + + var body = new Dictionary(); + + attributes[TelemetryConstants.Reason] = !string.IsNullOrWhiteSpace(details.Reason) ? details.Reason?.ToLowerInvariant() : Reason.Unknown; + attributes[TelemetryConstants.Variant] = details.Variant; + attributes[TelemetryFlagMetadata.ContextId] = details.FlagMetadata?.GetString(TelemetryFlagMetadata.ContextId); + attributes[TelemetryFlagMetadata.FlagSetId] = details.FlagMetadata?.GetString(TelemetryFlagMetadata.FlagSetId); + attributes[TelemetryFlagMetadata.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 ?? "N/A"; + } + } + + return new EvaluationEvent(EventName, attributes, body); + } +} diff --git a/src/OpenFeature/Telemetry/TelemetryConstants.cs b/src/OpenFeature/Telemetry/TelemetryConstants.cs new file mode 100644 index 00000000..3660c82d --- /dev/null +++ b/src/OpenFeature/Telemetry/TelemetryConstants.cs @@ -0,0 +1,53 @@ +namespace OpenFeature.Telemetry; + +/// +/// The attributes of an OpenTelemetry compliant event for flag evaluation. +/// +/// +public static class TelemetryConstants +{ + /// + /// The lookup key of the feature flag. + /// + public const string Key = "feature_flag.key"; + + /// + /// Describes a class of error the operation ended with. + /// + public const string ErrorCode = "error.type"; + + /// + /// A semantic identifier for an evaluated flag value. + /// + public const string Variant = "feature_flag.result.variant"; + + /// + /// The unique identifier for the flag evaluation context. For example, the targeting key. + /// + public const string ContextId = "feature_flag.context.id"; + + /// + /// A message explaining the nature of an error occurring during flag evaluation. + /// + public const string ErrorMessage = "error.message"; + + /// + /// The reason code which shows how a feature flag value was determined. + /// + public const string Reason = "feature_flag.result.reason"; + + /// + /// Describes a class of error the operation ended with. + /// + public const string Provider = "feature_flag.provider.name"; + + /// + /// The identifier of the flag set to which the feature flag belongs. + /// + public const string FlagSetId = "feature_flag.set.id"; + + /// + /// The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. + /// + public const string Version = "feature_flag.version"; +} diff --git a/src/OpenFeature/Telemetry/TelemetryEvaluationData.cs b/src/OpenFeature/Telemetry/TelemetryEvaluationData.cs new file mode 100644 index 00000000..f143dc02 --- /dev/null +++ b/src/OpenFeature/Telemetry/TelemetryEvaluationData.cs @@ -0,0 +1,20 @@ +namespace OpenFeature.Telemetry; + +/** +* Event data, sometimes referred to as "body", is specific to a specific event. +* In this case, the event is `feature_flag.evaluation`. That's why the prefix +* is omitted from the values. +* @see https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/ +*/ +public static class TelemetryEvaluationData +{ + /** + * The evaluated value of the feature flag. + * + * - type: `undefined` + * - requirement level: `conditionally required` + * - condition: variant is not defined on the evaluation details + * - example: `#ff0000`; `1`; `true` + */ + public const string Value = "value"; +} diff --git a/src/OpenFeature/Telemetry/TelemetryFlagMetadata.cs b/src/OpenFeature/Telemetry/TelemetryFlagMetadata.cs new file mode 100644 index 00000000..3bd0a258 --- /dev/null +++ b/src/OpenFeature/Telemetry/TelemetryFlagMetadata.cs @@ -0,0 +1,25 @@ +namespace OpenFeature.Telemetry; + +/** + * Well-known flag metadata attributes for telemetry events. + * @see https://openfeature.dev/specification/appendix-d#flag-metadata + */ +public static class TelemetryFlagMetadata +{ + /** + * 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. + */ + public const string ContextId = "contextId"; + + /** + * A logical identifier for the flag set. + */ + public const string FlagSetId = "flagSetId"; + + /** + * A version string (format unspecified) for the flag or flag set. + */ + public const string Version = "version"; +} diff --git a/test/OpenFeature.Tests/Telemetry/EvaluationEventBuilderTests.cs b/test/OpenFeature.Tests/Telemetry/EvaluationEventBuilderTests.cs new file mode 100644 index 00000000..99805f2b --- /dev/null +++ b/test/OpenFeature.Tests/Telemetry/EvaluationEventBuilderTests.cs @@ -0,0 +1,130 @@ +using System.Collections.Generic; +using OpenFeature.Constant; +using OpenFeature.Model; +using OpenFeature.Telemetry; +using Xunit; + +namespace OpenFeature.Tests.Telemetry; + +public class EvaluationEventBuilderTests +{ + [Fact] + public void Build_ShouldReturnEventWithCorrectAttributes() + { + // Arrange + var clientMetadata = new ClientMetadata("client", "1.0.0"); + var providerMetadata = new Metadata("provider"); + var hookContext = new HookContext("flagKey", new Value(), FlagValueType.Object, clientMetadata, + providerMetadata, EvaluationContext.Empty); + var metadata = new Dictionary + { + { "flagSetId", "flagSetId" }, { "contextId", "contextId" }, { "version", "version" } + }; + var flagMetadata = new ImmutableMetadata(metadata); + var details = new FlagEvaluationDetails("flagKey", new Value("value"), ErrorType.None, + reason: "reason", variant: "variant", flagMetadata: flagMetadata); + + // Act + var evaluationEvent = EvaluationEventBuilder.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[TelemetryFlagMetadata.ContextId]); + Assert.Equal("flagSetId", evaluationEvent.Attributes[TelemetryFlagMetadata.FlagSetId]); + Assert.Equal("version", evaluationEvent.Attributes[TelemetryFlagMetadata.Version]); + } + + [Fact] + public void Build_ShouldHandleErrorDetails() + { + // Arrange + var clientMetadata = new ClientMetadata("client", "1.0.0"); + var providerMetadata = new Metadata("provider"); + var hookContext = new HookContext("flagKey", new Value(), FlagValueType.Object, clientMetadata, + providerMetadata, EvaluationContext.Empty); + var metadata = new Dictionary + { + { "flagSetId", "flagSetId" }, { "contextId", "contextId" }, { "version", "version" } + }; + var flagMetadata = new ImmutableMetadata(metadata); + var details = new FlagEvaluationDetails("flagKey", new Value("value"), ErrorType.General, + errorMessage: "errorMessage", reason: "reason", variant: "variant", flagMetadata: flagMetadata); + + // Act + var evaluationEvent = EvaluationEventBuilder.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("flagKey", new Value("value"), FlagValueType.Object, clientMetadata, + providerMetadata, EvaluationContext.Empty); + var metadata = new Dictionary + { + { "flagSetId", "flagSetId" }, { "contextId", "contextId" }, { "version", "version" } + }; + var flagMetadata = new ImmutableMetadata(metadata); + var details = new FlagEvaluationDetails("flagKey", new Value("value"), ErrorType.None, + reason: "reason", variant: null, flagMetadata: flagMetadata); + + // Act + var evaluationEvent = EvaluationEventBuilder.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("flagKey", new Value("value"), FlagValueType.Object, clientMetadata, + providerMetadata, EvaluationContext.Empty); + var flagMetadata = new ImmutableMetadata(); + var details = new FlagEvaluationDetails("flagKey", new Value("value"), ErrorType.None, + reason: "reason", variant: "", flagMetadata: flagMetadata); + + // Act + var evaluationEvent = EvaluationEventBuilder.Build(hookContext, details); + + // Assert + Assert.Null(evaluationEvent.Attributes[TelemetryFlagMetadata.ContextId]); + Assert.Null(evaluationEvent.Attributes[TelemetryFlagMetadata.FlagSetId]); + Assert.Null(evaluationEvent.Attributes[TelemetryFlagMetadata.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("flagKey", new Value("value"), FlagValueType.Object, clientMetadata, + providerMetadata, EvaluationContext.Empty); + var flagMetadata = new ImmutableMetadata(); + var details = new FlagEvaluationDetails("flagKey", new Value("value"), ErrorType.None, + reason: reason, variant: "", flagMetadata: flagMetadata); + + // Act + var evaluationEvent = EvaluationEventBuilder.Build(hookContext, details); + + // Assert + Assert.Equal(Reason.Unknown, evaluationEvent.Attributes[TelemetryConstants.Reason]); + } +}