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