Add feature flagging semantic conventions (#2529)

CHANGELOG.md

@@ -30,6 +30,8 @@ release.
 
 - Add IBM Cloud as a cloud provider.
   ([#2965](https://github.com/open-telemetry/opentelemetry-specification/pull/2965))
+- Add semantic conventions for Feature Flags
+  ([#2529](https://github.com/open-telemetry/opentelemetry-specification/pull/2529))
 - Rename `rpc.request.metadata.<key>` and `rpc.response.metadata.<key>` to
   `rpc.grpc.request.metadata.<key>` and `rpc.grpc.response.metadata.<key>`
   ([#2981](https://github.com/open-telemetry/opentelemetry-specification/pull/2981))

semantic_conventions/logs/log-feature_flag.yaml

@@ -0,0 +1,11 @@
+groups:
+  - id: log-feature_flag
+    type: event
+    prefix: feature_flag
+    brief: >
+      This document defines attributes for feature flag evaluations
+      represented using Log Records.
+    attributes:
+      - ref: feature_flag.key
+      - ref: feature_flag.provider_name
+      - ref: feature_flag.variant

semantic_conventions/trace/feature-flag.yaml

@@ -0,0 +1,34 @@
+groups:
+  - id: feature_flag
+    prefix: feature_flag
+    type: event
+    brief: >
+      This semantic convention defines the attributes used to represent a
+      feature flag evaluation as an event.
+    attributes:
+      - id: key
+        type: string
+        requirement_level: required
+        brief: The unique identifier of the feature flag.
+        examples: ["logo-color"]
+      - id: provider_name
+        type: string
+        requirement_level: recommended
+        brief: The name of the service provider that performs the flag evaluation.
+        examples: ["Flag Manager"]
+      - id: variant
+        type: string
+        requirement_level: recommended
+        examples: ["red", "true", "on"]
+        brief: >
+          SHOULD be a semantic identifier for a value. If one is unavailable, a
+          stringified version of the value can be used.
+        note: |-
+          A semantic identifier, commonly referred to as a variant, provides a means
+          for referring to a value without including the value itself. This can
+          provide additional context for understanding the meaning behind a value.
+          For example, the variant `red` maybe be used for the value `#c05543`.
+
+          A stringified version of the value can be used in situations where a
+          semantic identifier is unavailable. String representation of the value
+          should be determined by the implementer.

specification/logs/semantic_conventions/feature-flags.md

@@ -0,0 +1,53 @@
+# Semantic Conventions for Feature Flag Evaluations
+
+**Status**: [Experimental](../../document-status.md)
+
+This document defines semantic conventions for recording feature flag evaluations as
+a [log record](../api.md#logrecord) emitted through the
+[Logger API](../api.md#emit-logrecord).
+This is useful when a flag is evaluated outside of a transaction context
+such as when the application loads or on a timer.
+To record a flag evaluation as a part of a transaction context,
+consider [recording it as a span event](../../trace/semantic_conventions/feature-flags.md).
+
+For more information about why it is useful to capture feature flag evaluations,
+refer to the [motivation](../../trace/semantic_conventions/feature-flags.md#motivation)
+section of the trace semantic convention for feature flag evaluations.
+
+<!-- toc -->
+
+- [Recording an Evaluation](#recording-an-evaluation)
+- [Attributes](#attributes)
+
+<!-- tocstop -->
+
+## Recording an Evaluation
+
+Feature flag evaluations SHOULD be recorded as attributes on the
+[LogRecord](../api.md#logrecord) passed to the [Logger](../api.md#logger) emit
+operations. Evaluations MAY be recorded on "logs" or "events" depending on the
+context.
+
+## Attributes
+
+The table below indicates which attributes should be added to the
+[LogRecord](../api.md#logrecord) and their types.
+
+<!-- semconv log-feature_flag -->
+The event name MUST be `feature_flag`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`feature_flag.key`](../../trace/semantic_conventions/feature-flags.md) | string | The unique identifier of the feature flag. | `logo-color` | Required |
+| [`feature_flag.provider_name`](../../trace/semantic_conventions/feature-flags.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended |
+| [`feature_flag.variant`](../../trace/semantic_conventions/feature-flags.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended |
+
+**[1]:** A semantic identifier, commonly referred to as a variant, provides a means
+for referring to a value without including the value itself. This can
+provide additional context for understanding the meaning behind a value.
+For example, the variant `red` maybe be used for the value `#c05543`.
+
+A stringified version of the value can be used in situations where a
+semantic identifier is unavailable. String representation of the value
+should be determined by the implementer.
+<!-- endsemconv -->

specification/trace/semantic_conventions/README.md

@@ -23,6 +23,7 @@ The following semantic conventions for spans are defined:
 * [FaaS](faas.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans.
 * [Exceptions](exceptions.md): For recording exceptions associated with a span.
 * [Compatibility](compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer.
+* [Feature Flags](feature-flags.md): For recording feature flag evaluations associated with a span.
 
 The following library-specific semantic conventions are defined:
 

specification/trace/semantic_conventions/feature-flags.md

@@ -0,0 +1,57 @@
+# Semantic conventions for Feature Flags
+
+**Status**: [Experimental](../../document-status.md)
+
+This document defines semantic conventions for recording dynamic feature flag
+evaluations within a transaction as span events.
+To record an evaluation outside of a transaction context, consider
+[recording it as a log record](../../logs/semantic_conventions/feature-flags.md).
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [Motivation](#motivation)
+- [Overview](#overview)
+- [Convention](#convention)
+
+<!-- tocstop -->
+
+## Motivation
+
+Features flags are commonly used in modern applications to decouple feature releases from deployments.
+Many feature flagging tools support the ability to update flag configurations in near real-time from a remote feature flag management service.
+They also commonly allow rulesets to be defined that return values based on contextual information.
+For example, a feature could be enabled only for a specific subset of users based on context (e.g. users email domain, membership tier, country).
+
+Since feature flags are dynamic and affect runtime behavior, it's important to collect relevant feature flag telemetry signals.
+This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases.
+
+## Overview
+
+The following semantic convention defines how feature flags can be represented as an `Event` in OpenTelemetry.
+The terminology was defined in the [OpenFeature specification](https://docs.openfeature.dev/docs/specification/), which represents an industry consensus.
+It's intended to be vendor neutral and provide flexibility for current and future use cases.
+
+## Convention
+
+A flag evaluation SHOULD be recorded as an Event on the span during which it occurred.
+
+<!-- semconv feature_flag -->
+The event name MUST be `feature_flag`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | Required |
+| `feature_flag.provider_name` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended |
+| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended |
+
+**[1]:** A semantic identifier, commonly referred to as a variant, provides a means
+for referring to a value without including the value itself. This can
+provide additional context for understanding the meaning behind a value.
+For example, the variant `red` maybe be used for the value `#c05543`.
+
+A stringified version of the value can be used in situations where a
+semantic identifier is unavailable. String representation of the value
+should be determined by the implementer.
+<!-- endsemconv -->