From 6cc48a5ad0556c54cd15a6255c1bc8345f8e45c8 Mon Sep 17 00:00:00 2001
From: Michael Beemer <michael.beemer@dynatrace.com>
Date: Tue, 10 May 2022 17:11:53 -0400
Subject: [PATCH] Add feature flagging semantic conventions

---
 semantic_conventions/trace/feature-flag.yaml  | 49 +++++++++++++++++
 .../trace/semantic_conventions/README.md      |  1 +
 .../semantic_conventions/feature-flags.md     | 53 +++++++++++++++++++
 3 files changed, 103 insertions(+)
 create mode 100644 semantic_conventions/trace/feature-flag.yaml
 create mode 100644 specification/trace/semantic_conventions/feature-flags.md

diff --git a/semantic_conventions/trace/feature-flag.yaml b/semantic_conventions/trace/feature-flag.yaml
new file mode 100644
index 00000000000..c5352af78e6
--- /dev/null
+++ b/semantic_conventions/trace/feature-flag.yaml
@@ -0,0 +1,49 @@
+groups:
+  - id: feature_flag
+    prefix: feature_flag
+    brief: >
+      This semantic convention defines the attributes used to represent a
+      feature flag evaluation as a span.
+    span_kind: internal
+    attributes:
+      - id: flag_key
+        type: string
+        required: always
+        brief: The unique identifier of the feature flag.
+        examples: ["show-new-logo"]
+  - id: feature_flag.provider
+    prefix: feature_flag.provider
+    extends: feature_flag
+    brief: Semantic convention for the provider performing the flag evaluation.
+    attributes:
+      - id: name
+        type: string
+        required: always
+        brief: The name of the provider performing the flag evaluation.
+        examples: ["Flag Manager"]
+      - id: management_url
+        type: string
+        brief: The URL used to manage the feature flag in the provider.
+        examples: ["http://localhost:4200/flags/1"]
+  - id: feature_flag.evaluated
+    prefix: feature_flag.evaluated
+    extends: feature_flag
+    brief: Semantic convection for the values evaluated by provider.
+    attributes:
+      - id: variant
+        type: string
+        brief: The name associated with the evaluated value.
+        examples: ["reverse"]
+        required:
+          conditional: >
+            A variant should be used if it is available. If the variant is
+            present, feature_flag.evaluated.value should be omitted.
+      - id: value
+        type: string
+        brief: A string representation of the evaluated value.
+        examples: ["true", "red", "on"]
+        required:
+          conditional: >
+            The value should only be used if the variant is not available. How
+            the value is represented as a string should be determined by the
+            implementer.
diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md
index 34c54b40350..5336a646a8d 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 spans that represent a feature flag evaluation.
 
 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..35ffbbd32e2
--- /dev/null
+++ b/specification/trace/semantic_conventions/feature-flags.md
@@ -0,0 +1,53 @@
+# Semantic conventions for Feature Flags
+
+**Status**: [Experimental](../../../document-status.md)
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [General Attributes](#general-attributes)
+- [Provider Attributes](#provider-attributes)
+- [Evaluated Attributes](#evaluated-attributes)
+
+<!-- tocstop -->
+
+**Span kind:** MUST always be `INTERNAL`.
+
+Span `name` should be a combination of the provider name and the name of the function used when evaluating the flag, separated by a hyphen. For example, `unleash - isEnabled` or `my flag eval - getBoolValue`.
+
+## General Attributes
+
+This section describes the general attributes that are used for flag evaluation.
+
+<!-- semconv feature_flag -->
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `feature_flag.flag_key` | string | The unique identifier of the feature flag. | `show-new-logo` | Yes |
+<!-- endsemconv -->
+
+## Provider Attributes
+
+This section describes the provider that was used to perform the flag evaluation.
+
+<!-- semconv feature_flag.provider -->
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `feature_flag.provider.name` | string | The name of the provider performing the flag evaluation. | `Flag Manager` | Yes |
+| `feature_flag.provider.management_url` | string | The URL used to manage the feature flag in the provider. | `http://localhost:4200/flags/1` | No |
+<!-- endsemconv -->
+
+## Evaluated Attributes
+
+This section describes how flag evaluations can be represented on a span.
+
+<!-- semconv feature_flag.evaluated -->
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `feature_flag.evaluated.variant` | string | The name associated with the evaluated value. | `reverse` | Conditional [1] |
+| `feature_flag.evaluated.value` | string | A string representation of the evaluated value. | `true`; `red`; `on` | Conditional [2] |
+
+**[1]:** A variant should be used if it is available. If the variant is present, feature_flag.evaluated.value should be omitted.
+
+**[2]:** The value should only be used if the variant is not available. How the value is represented as a string should be determined by the implementer.
+<!-- endsemconv -->