From 216a4d1372514d0cb9df1346a9a80f516e0764f8 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Mon, 14 Apr 2025 21:09:07 +0000 Subject: [PATCH 1/3] update the observability appendix to include the latest otel semcon Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 32 ++++++++++++++++------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index c9fcfc32..620fcbd9 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -19,21 +19,21 @@ This is particularly relevant to telemetry-related [hooks](./sections/04-hooks.m The following describes how fields on the [evaluation details](types.md#evaluation-details) are mapped to feature flag log records: -| Log Record Attribute | Source Field or Derived Value from Evaluation Details | Requirement level | Notes | -| --------------------------------------- | ----------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `feature_flag.key` | `flag key` | `Required` | See: [flag key](./glossary.md#flag-key) | -| `error.type` | `error code` | `Conditionally Required` [^1] | See: [error code](./types.md#error-code), | -| `feature_flag.evaluation.error.message` | `error message` | `Conditionally Required` [^1] | A human-readable error message associated with a failed evaluation. For programmatic purposes, refer to `error code`. | -| `feature_flag.variant` | `variant` | `Conditionally Required` [^2] | See: [variant](./glossary.md#variant) | -| `feature_flag.evaluation.reason` | `reason` | `Recommended` | See: [reason](./types.md#resolution-reason) | +| Log Record Attribute | Source Field or Derived Value from Evaluation Details | Requirement level | Notes | +| ----------------------------- | ----------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `feature_flag.key` | `flag key` | `Required` | See: [flag key](./glossary.md#flag-key) | +| `feature_flag.result.variant` | `variant` | `Conditionally Required` [^2] | See: [variant](./glossary.md#variant) | +| `feature_flag.result.reason` | `reason` | `Recommended` | See: [reason](./types.md#resolution-reason) | +| `error.type` | `error code` | `Conditionally Required` [^1] | See: [error code](./types.md#error-code), | +| `error.message` | `error message` | `Conditionally Required` [^1] | A human-readable error message associated with a failed evaluation. For programmatic purposes, refer to `error code`. | > [!NOTE] -> The `error.type` and `feature_flag.evaluation.reason` enumerations use a lowercase "snake_case" convention (see [OpenTelemetry feature-flag log records][otel-ff-logs]). +> The `error.type` and `feature_flag.result.reason` enumerations use a lowercase "snake_case" convention (see [OpenTelemetry feature-flag log records][otel-ff-logs]). > OpenFeature [error codes](types.md#error-code) and [resolution reasons](./types.md#resolution-reason) should be transformed accordingly by integrations which include this data. #### Flag Value -The flag value is required if the `feature_flag.variant` is not set (and optional otherwise), and is defined in a the event body: +The flag value is required if the `feature_flag.result.variant` is not set (and optional otherwise), and is defined in a the event body: | Body Field | Source Field from Evaluation Details | Requirement level | Notes | | ---------- | ------------------------------------ | ----------------------------- | ------------------------------------------- | @@ -56,7 +56,19 @@ The following describes how keys in [flag metadata](types.md#flag-metadata) are | Log Record Attribute | Provider Metadata Field | Requirement level | Notes | | ---------------------------- | ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------ | -| `feature_flag.provider_name` | `name` | `Recommended` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. | +| `feature_flag.provider.name` | `name` | `Recommended` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. | + +## History + +Feature flags in the OpenTelemetry semantic conventions are currently in development and are marked as experimental. +The following table describes the history of changes to the OpenTelemetry feature flag log records as it progresses towards a stable release. + +| Original Field Name | New Field Name | Semantic Convention Release | +| --------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------- | +| `feature_flag.evaluation.error.message` | `error.message` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | +| `feature_flag.variant` | `feature_flag.result.variant` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | +| `feature_flag.evaluation.reason` | `feature_flag.result.reason` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | +| `feature_flag.provider_name` | `feature_flag.provider.name` | Unreleased | ## Footnotes From 6413ece0f2a7240dadf37f796d92593da1b60149 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Wed, 23 Apr 2025 18:01:53 +0000 Subject: [PATCH 2/3] remove body, add feature_flag.result.value Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 46 ++++++++++------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 620fcbd9..205c2f21 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -19,44 +19,37 @@ This is particularly relevant to telemetry-related [hooks](./sections/04-hooks.m The following describes how fields on the [evaluation details](types.md#evaluation-details) are mapped to feature flag log records: -| Log Record Attribute | Source Field or Derived Value from Evaluation Details | Requirement level | Notes | -| ----------------------------- | ----------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `feature_flag.key` | `flag key` | `Required` | See: [flag key](./glossary.md#flag-key) | -| `feature_flag.result.variant` | `variant` | `Conditionally Required` [^2] | See: [variant](./glossary.md#variant) | -| `feature_flag.result.reason` | `reason` | `Recommended` | See: [reason](./types.md#resolution-reason) | -| `error.type` | `error code` | `Conditionally Required` [^1] | See: [error code](./types.md#error-code), | -| `error.message` | `error message` | `Conditionally Required` [^1] | A human-readable error message associated with a failed evaluation. For programmatic purposes, refer to `error code`. | +| Log Record Attribute | Source Field or Derived Value from Evaluation Details | Requirement level | Type | Notes | +| ----------------------------- | ----------------------------------------------------- | ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- | +| `feature_flag.key` | `flag key` | `Required` | `string` | See: [flag key](./glossary.md#flag-key) | +| `feature_flag.result.variant` | `variant` | `Conditionally Required` [^1] | `string` | See: [variant](./glossary.md#variant) | +| `feature_flag.result.value` | `value` | `Conditionally Required` [^2] | `undefined` | See: [value](./glossary.md#values) | +| `feature_flag.result.reason` | `reason` | `Recommended` | `string` | See: [reason](./types.md#resolution-reason) | +| `error.type` | `error code` | `Conditionally Required` [^3] | `string` | See: [error code](./types.md#error-code), | +| `error.message` | `error message` | `Conditionally Required` [^3] | `string` | A human-readable error message associated with a failed evaluation. For programmatic purposes, refer to `error code`. | > [!NOTE] > The `error.type` and `feature_flag.result.reason` enumerations use a lowercase "snake_case" convention (see [OpenTelemetry feature-flag log records][otel-ff-logs]). > OpenFeature [error codes](types.md#error-code) and [resolution reasons](./types.md#resolution-reason) should be transformed accordingly by integrations which include this data. -#### Flag Value - -The flag value is required if the `feature_flag.result.variant` is not set (and optional otherwise), and is defined in a the event body: - -| Body Field | Source Field from Evaluation Details | Requirement level | Notes | -| ---------- | ------------------------------------ | ----------------------------- | ------------------------------------------- | -| `value` | `value` | `Conditionally Required` [^3] | The type of the `value` field is undefined. | - ### Flag Metadata The following describes how keys in [flag metadata](types.md#flag-metadata) are mapped to feature flag log records: -| Log Record Attribute | Flag Metadata Key | Requirement level | Notes | -| ------------------------- | ----------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `feature_flag.context.id` | `contextId` | `Recommended` | The context identifier returned in the flag metadata uniquely identifies the subject of the flag evaluation. If not available, the [targeting key](./glossary.md#targeting-key) should be used. | -| `feature_flag.set.id` | `flagSetId` | `Recommended` | A logical identifier for the [flag set](./glossary.md#flag-set). | -| `feature_flag.version` | `version` | `Recommended` | A version string (format unspecified) for the flag or [flag set](./glossary.md#flag-set). | +| Log Record Attribute | Flag Metadata Key | Requirement level | Type | Notes | +| ------------------------- | ----------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `feature_flag.context.id` | `contextId` | `Recommended` | `string` | The context identifier returned in the flag metadata uniquely identifies the subject of the flag evaluation. If not available, the [targeting key](./glossary.md#targeting-key) should be used. | +| `feature_flag.set.id` | `flagSetId` | `Recommended` | `string` | A logical identifier for the [flag set](./glossary.md#flag-set). | +| `feature_flag.version` | `version` | `Recommended` | `string` | A version string (format unspecified) for the flag or [flag set](./glossary.md#flag-set). | > [!NOTE] > Keys in flag metadata use the "camelCase" casing convention, while the OpenTelemetry standard uses a namespaced "snake_case" convention. ### Provider Metadata -| Log Record Attribute | Provider Metadata Field | Requirement level | Notes | -| ---------------------------- | ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------ | -| `feature_flag.provider.name` | `name` | `Recommended` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. | +| Log Record Attribute | Provider Metadata Field | Requirement level | Type | Notes | +| ---------------------------- | ----------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------ | +| `feature_flag.provider.name` | `name` | `Recommended` | `string` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. | ## History @@ -68,12 +61,13 @@ The following table describes the history of changes to the OpenTelemetry featur | `feature_flag.evaluation.error.message` | `error.message` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | | `feature_flag.variant` | `feature_flag.result.variant` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | | `feature_flag.evaluation.reason` | `feature_flag.result.reason` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | +| `value` | `feature_flag.result.value` | Unreleased | | `feature_flag.provider_name` | `feature_flag.provider.name` | Unreleased | ## Footnotes -[^1]: Include if and only if an error occurred during a flag evaluation. -[^2]: The `variant` field is required if the `value` field is not set. -[^3]: The `value` field is required if the `variant` field is not set. +[^1]: The `variant` field is required if the `value` field is not set. +[^2]: The `value` field is required if the `variant` field is not set. +[^3]: Include if and only if an error occurred during a flag evaluation. [otel-ff-logs]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/ From 78fbe605acb4dc7f8b4d52db18103620bb14756c Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Mon, 5 May 2025 20:32:49 +0000 Subject: [PATCH 3/3] add release version info, update footnote comments Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 205c2f21..9e33e28b 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -58,16 +58,16 @@ The following table describes the history of changes to the OpenTelemetry featur | Original Field Name | New Field Name | Semantic Convention Release | | --------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------- | -| `feature_flag.evaluation.error.message` | `error.message` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | | `feature_flag.variant` | `feature_flag.result.variant` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | | `feature_flag.evaluation.reason` | `feature_flag.result.reason` | [v1.32.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.32.0) | -| `value` | `feature_flag.result.value` | Unreleased | -| `feature_flag.provider_name` | `feature_flag.provider.name` | Unreleased | +| `feature_flag.evaluation.error.message` | `error.message` | [v1.33.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.33.0) | +| `feature_flag.provider_name` | `feature_flag.provider.name` | [v1.33.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.33.0) | +| `value` | `feature_flag.result.value` | Unreleased | ## Footnotes -[^1]: The `variant` field is required if the `value` field is not set. -[^2]: The `value` field is required if the `variant` field is not set. -[^3]: Include if and only if an error occurred during a flag evaluation. +[^1]: The `variant` field should be included whenever possible as it represents the symbolic name of the flag's returned value (e.g., "on"/"off", "control"/"treatment"). Only omit if the provider doesn't supply this information. +[^2]: The `value` field should be included whenever a `variant` is unavailable. Large or sensitive values should be redacted or omitted prior to being captured in telemetry signals. +[^3]: Include `error.type` and `error.message`, if and only if an error occurred during a flag evaluation. [otel-ff-logs]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/