diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f6fdffff32..bb3ae4037f7 100644 --- a/CHANGELOG.md +++ b/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.` and `rpc.response.metadata.` to `rpc.grpc.request.metadata.` and `rpc.grpc.response.metadata.` ([#2981](https://github.com/open-telemetry/opentelemetry-specification/pull/2981)) diff --git a/semantic_conventions/logs/log-feature_flag.yaml b/semantic_conventions/logs/log-feature_flag.yaml new file mode 100644 index 00000000000..6d902423f59 --- /dev/null +++ b/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 diff --git a/semantic_conventions/trace/feature-flag.yaml b/semantic_conventions/trace/feature-flag.yaml new file mode 100644 index 00000000000..50706ba2d7b --- /dev/null +++ b/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. diff --git a/specification/logs/semantic_conventions/feature-flags.md b/specification/logs/semantic_conventions/feature-flags.md new file mode 100644 index 00000000000..c248555a58f --- /dev/null +++ b/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. + + + +- [Recording an Evaluation](#recording-an-evaluation) +- [Attributes](#attributes) + + + +## 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. + + +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. + diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md index 34c54b40350..78656e96710 100644 --- a/specification/trace/semantic_conventions/README.md +++ b/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: diff --git a/specification/trace/semantic_conventions/feature-flags.md b/specification/trace/semantic_conventions/feature-flags.md new file mode 100644 index 00000000000..1b7b5862b1e --- /dev/null +++ b/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). + + + + + +- [Motivation](#motivation) +- [Overview](#overview) +- [Convention](#convention) + + + +## 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. + + +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. +