diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f7337fe01..5472da421 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -20,11 +20,12 @@ /internal/tools/schema_check.sh @open-telemetry/specs-semconv-approvers @tigrannajaryan # Logs semantic conventions -/semantic_conventions/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/exceptions/exceptions-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/general/events-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/general/logs-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan +/semantic_conventions/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan +/specification/exceptions/exceptions-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/specification/feature-flags/feature-flags-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/specification/general/events-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/specification/general/logs-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/specification/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan # JVM semantic conventions approvers /semantic_conventions/metrics/process-runtime-jvm-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers diff --git a/specification/README.md b/specification/README.md index 8d4174947..b5278dd9a 100644 --- a/specification/README.md +++ b/specification/README.md @@ -10,6 +10,7 @@ Semantic Conventions are defined for the following areas: * [Exceptions](exceptions/README.md): Semantic Conventions for Exceptions. * [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations. * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification. +* [Feature Flags](http/README.md): Semantic Conventions for feature flag evaluations. * [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. * [Database](database/README.md): Semantic Conventions for database operations. * [RPC](rpc/README.md): Semantic Conventions for RPC client and server operations. diff --git a/specification/feature-flags/README.md b/specification/feature-flags/README.md new file mode 100644 index 000000000..249b82fa5 --- /dev/null +++ b/specification/feature-flags/README.md @@ -0,0 +1,13 @@ +# Semantic conventions for Feature Flags + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for recording dynamic feature flag +evaluations in spans and logs. + +Semantic conventions for feature flags are defined for the following signals: + +* [Feature Flags in Spans](feature-flags-spans.md): Semantic Conventions for recording feature flags in *spans*. +* [Feature Flags in Logs](feature-flags-logs.md): Semantic Conventions for recording feature flags in *logs*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/logs/semantic_conventions/feature-flags.md b/specification/feature-flags/feature-flags-logs.md similarity index 74% rename from specification/logs/semantic_conventions/feature-flags.md rename to specification/feature-flags/feature-flags-logs.md index 78b639985..3fc86fa2d 100644 --- a/specification/logs/semantic_conventions/feature-flags.md +++ b/specification/feature-flags/feature-flags-logs.md @@ -1,4 +1,4 @@ -# Semantic Conventions for Feature Flag Evaluations +# Semantic Conventions for Feature Flags in Logs **Status**: [Experimental][DocumentStatus] @@ -8,10 +8,10 @@ a [log record](https://github.com/open-telemetry/opentelemetry-specification/tre 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). +consider [recording it as a span event](feature-flags-spans.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) +refer to the [motivation](feature-flags-spans.md#motivation) section of the trace semantic convention for feature flag evaluations. @@ -38,9 +38,9 @@ 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 | +| [`feature_flag.key`](feature-flags-spans.md) | string | The unique identifier of the feature flag. | `logo-color` | Required | +| [`feature_flag.provider_name`](feature-flags-spans.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended | +| [`feature_flag.variant`](feature-flags-spans.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 diff --git a/specification/trace/semantic_conventions/feature-flags.md b/specification/feature-flags/feature-flags-spans.md similarity index 95% rename from specification/trace/semantic_conventions/feature-flags.md rename to specification/feature-flags/feature-flags-spans.md index d88fbc04c..a40a8d8cf 100644 --- a/specification/trace/semantic_conventions/feature-flags.md +++ b/specification/feature-flags/feature-flags-spans.md @@ -1,11 +1,11 @@ -# Semantic conventions for Feature Flags +# Semantic conventions for Feature Flags in Spans **Status**: [Experimental][DocumentStatus] 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). +[recording it as a log record](feature-flags-logs.md). diff --git a/specification/general/logs-general.md b/specification/general/logs-general.md index 562ac4d39..6a67b3f3a 100644 --- a/specification/general/logs-general.md +++ b/specification/general/logs-general.md @@ -20,7 +20,7 @@ The following semantic conventions for logs are defined: * [General](#general-log-identification-attributes): General semantic attributes that may be used in describing Log Records. * [Exceptions](/specification/exceptions/exceptions-logs.md): Semantic attributes that may be used in describing exceptions in logs. -* [Feature Flags](/specification/logs/semantic_conventions/feature-flags.md): Semantic attributes that may be used in describing feature flag evaluations in logs. +* [Feature Flags](/specification/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs. Apart from semantic conventions for logs, [events](events-general.md), [traces](trace-general.md), and [metrics](metrics-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own diff --git a/specification/general/trace-general.md b/specification/general/trace-general.md index 469c424d4..763654f87 100644 --- a/specification/general/trace-general.md +++ b/specification/general/trace-general.md @@ -23,7 +23,7 @@ The following semantic conventions for spans are defined: * [FaaS](/specification/faas/faas-spans.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. * [Exceptions](/specification/exceptions/exceptions-spans.md): For recording exceptions associated with a span. * [Compatibility](trace-compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer. -* [Feature Flags](/specification/trace/semantic_conventions/feature-flags.md): For recording feature flag evaluations associated with a span. +* [Feature Flags](/specification/feature-flags/feature-flags-spans.md): For recording feature flag evaluations associated with a span. The following library-specific semantic conventions are defined: