From 7e6ed38ced019e20898987b124a75598a52a3ec7 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Tue, 28 Jan 2025 14:36:28 -0500 Subject: [PATCH 1/3] chore: remove flag type property Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index a06d97a3..315a783c 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -26,7 +26,6 @@ The following describes how fields on the [evaluation details](types.md#evaluati | `feature_flag.variant` | `variant` | See: [variant](./glossary.md#variant) | | `feature_flag.evaluation.error.message` | `error message` | A human-readable error message associated with a failed evaluation. For programmatic purposes, refer to `error code`. | | `feature_flag.evaluation.reason` | `reason` | See: [reason](./types.md#resolution-reason) | -| `feature_flag.evaluation.value.type` | One of `"array"`, `"boolean"`, `"byte_array"`, `"float"`, `"int"`, `"map"`, `"null"`, `"string"` or `"unknown"`, representing the type of the `evaluation details'` `value` field | See: [reason](./types.md#resolution-reason) | > [!NOTE] > The `error.type` and `feature_flag.evaluation.reason` enumerations use a lowercase "snake_case" convention (see [OpenTelemetry feature-flag log records](https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/)). From 1059d1e42afef77a606efbd3c2e371376ca60a83 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Thu, 30 Jan 2025 14:24:14 +0000 Subject: [PATCH 2/3] feat: enhance appendix D with requirement levels and improved references Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 48 +++++++++++++---------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 315a783c..797c65ad 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -8,7 +8,7 @@ sidebar_position: 5 # Appendix D: Observability This document describes conventions for extracting data from the OpenFeature SDK for use in telemetry signals. -It primarily focuses on providing recommendations for mapping well-known fields in OpenFeature to [OpenTelemetry feature-flag log records](https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/) and other semantic conventions. +It primarily focuses on providing recommendations for mapping well-known fields in OpenFeature to [OpenTelemetry feature-flag log records][otel-ff-logs] and other semantic conventions. ## Evaluations @@ -19,41 +19,49 @@ 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 | Notes | -| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `feature_flag.key` | `flag key` | See: [flag key](./glossary.md#flag-key) | -| `error.type` | `error code` | See: [error code](./types.md#error-code) | -| `feature_flag.variant` | `variant` | See: [variant](./glossary.md#variant) | -| `feature_flag.evaluation.error.message` | `error message` | A human-readable error message associated with a failed evaluation. For programmatic purposes, refer to `error code`. | -| `feature_flag.evaluation.reason` | `reason` | 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) | +| `error.type` | `error code` | `Conditionally Required` [^1] | See: [error code](./types.md#error-code), | +| `feature_flag.variant` | `variant` | `Conditionally Required` [^2] | See: [variant](./glossary.md#variant) | +| `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.evaluation.reason` | `reason` | `Recommended` | See: [reason](./types.md#resolution-reason) | > [!NOTE] -> The `error.type` and `feature_flag.evaluation.reason` enumerations use a lowercase "snake_case" convention (see [OpenTelemetry feature-flag log records](https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/)). +> The `error.type` and `feature_flag.evaluation.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: -| Body Field | Source Field from Evaluation Details | Notes | -| ---------- | ------------------------------------ | ------------------------------------------- | -| `value` | `value` | The type of the `value` field is undefined. | +| 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 | Notes | -| ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `feature_flag.context.id` | `contextId` | 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` | A logical identifier for the [flag set](./glossary.md#flag-set). | -| `feature_flag.version` | `version` | A version string (format unspecified) for the flag or [flag set](./glossary.md#flag-set). | +| 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). | > [!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 | Notes | -| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ | -| `feature_flag.provider_name` | `name` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. | +| 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`. | + +// Links + +[otel-ff-logs]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/ + +[^1]: 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. From 8dc1dacd3c39bb15b6d5e5f47d57fe650787a21f Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Thu, 30 Jan 2025 19:25:08 +0000 Subject: [PATCH 3/3] fix: correct formatting and wording in appendix D observability section Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 797c65ad..c9fcfc32 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -23,11 +23,11 @@ The following describes how fields on the [evaluation details](types.md#evaluati | --------------------------------------- | ----------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `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.variant` | `variant` | `Conditionally Required` [^2] | See: [variant](./glossary.md#variant) | | `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) | -> [!NOTE] +> [!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]). > OpenFeature [error codes](types.md#error-code) and [resolution reasons](./types.md#resolution-reason) should be transformed accordingly by integrations which include this data. @@ -49,7 +49,7 @@ The following describes how keys in [flag metadata](types.md#flag-metadata) are | `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). | -> [!NOTE] +> [!NOTE] > Keys in flag metadata use the "camelCase" casing convention, while the OpenTelemetry standard uses a namespaced "snake_case" convention. ### Provider Metadata @@ -58,10 +58,10 @@ The following describes how keys in [flag metadata](types.md#flag-metadata) are | ---------------------------- | ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------ | | `feature_flag.provider_name` | `name` | `Recommended` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. | -// Links - -[otel-ff-logs]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/ +## Footnotes -[^1]: If and only if an error occurred during a flag evaluation. +[^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. + +[otel-ff-logs]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/