Skip to content

Commit 8d6eeb3

Browse files
beeme1mrbeeme1mr
authored
chore!: remove flag type property, add requirement level and footnotes (#292)
Signed-off-by: Michael Beemer <[email protected]>
1 parent 5b07065 commit 8d6eeb3

File tree

1 file changed

+31
-24
lines changed

1 file changed

+31
-24
lines changed

‎specification/appendix-d-observability.md‎

Lines changed: 31 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ sidebar_position: 5
88
# Appendix D: Observability
99

1010
This document describes conventions for extracting data from the OpenFeature SDK for use in telemetry signals.
11-
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.
11+
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.
1212

1313
## Evaluations
1414

@@ -19,42 +19,49 @@ This is particularly relevant to telemetry-related [hooks](./sections/04-hooks.m
1919

2020
The following describes how fields on the [evaluation details](types.md#evaluation-details) are mapped to feature flag log records:
2121

22-
| Log Record Attribute | Source Field or Derived Value from Evaluation Details | Notes |
23-
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
24-
| `feature_flag.key` | `flag key` | See: [flag key](./glossary.md#flag-key) |
25-
| `error.type` | `error code` | See: [error code](./types.md#error-code) |
26-
| `feature_flag.variant` | `variant` | See: [variant](./glossary.md#variant) |
27-
| `feature_flag.evaluation.error.message` | `error message` | A human-readable error message associated with a failed evaluation. For programmatic purposes, refer to `error code`. |
28-
| `feature_flag.evaluation.reason` | `reason` | See: [reason](./types.md#resolution-reason) |
29-
| `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) |
30-
31-
> [!NOTE]
32-
> 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/)).
22+
| Log Record Attribute | Source Field or Derived Value from Evaluation Details | Requirement level | Notes |
23+
| --------------------------------------- | ----------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
24+
| `feature_flag.key` | `flag key` | `Required` | See: [flag key](./glossary.md#flag-key) |
25+
| `error.type` | `error code` | `Conditionally Required` [^1] | See: [error code](./types.md#error-code), |
26+
| `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`. |
27+
| `feature_flag.variant` | `variant` | `Conditionally Required` [^2] | See: [variant](./glossary.md#variant) |
28+
| `feature_flag.evaluation.reason` | `reason` | `Recommended` | See: [reason](./types.md#resolution-reason) |
29+
30+
> [!NOTE]
31+
> The `error.type` and `feature_flag.evaluation.reason` enumerations use a lowercase "snake_case" convention (see [OpenTelemetry feature-flag log records][otel-ff-logs]).
3332
> OpenFeature [error codes](types.md#error-code) and [resolution reasons](./types.md#resolution-reason) should be transformed accordingly by integrations which include this data.
3433
3534
#### Flag Value
3635

3736
The flag value is required if the `feature_flag.variant` is not set (and optional otherwise), and is defined in a the event body:
3837

39-
| Body Field | Source Field from Evaluation Details | Notes |
40-
| ---------- | ------------------------------------ | ------------------------------------------- |
41-
| `value` | `value` | The type of the `value` field is undefined. |
38+
| Body Field | Source Field from Evaluation Details | Requirement level | Notes |
39+
| ---------- | ------------------------------------ | ----------------------------- | ------------------------------------------- |
40+
| `value` | `value` | `Conditionally Required` [^3] | The type of the `value` field is undefined. |
4241

4342
### Flag Metadata
4443

4544
The following describes how keys in [flag metadata](types.md#flag-metadata) are mapped to feature flag log records:
4645

47-
| Log Record Attribute | Flag Metadata Key | Notes |
48-
| ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49-
| `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. |
50-
| `feature_flag.set.id` | `flagSetId` | A logical identifier for the [flag set](./glossary.md#flag-set). |
51-
| `feature_flag.version` | `version` | A version string (format unspecified) for the flag or [flag set](./glossary.md#flag-set). |
46+
| Log Record Attribute | Flag Metadata Key | Requirement level | Notes |
47+
| ------------------------- | ----------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
48+
| `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. |
49+
| `feature_flag.set.id` | `flagSetId` | `Recommended` | A logical identifier for the [flag set](./glossary.md#flag-set). |
50+
| `feature_flag.version` | `version` | `Recommended` | A version string (format unspecified) for the flag or [flag set](./glossary.md#flag-set). |
5251

53-
> [!NOTE]
52+
> [!NOTE]
5453
> Keys in flag metadata use the "camelCase" casing convention, while the OpenTelemetry standard uses a namespaced "snake_case" convention.
5554
5655
### Provider Metadata
5756

58-
| Log Record Attribute | Provider Metadata Field | Notes |
59-
| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
60-
| `feature_flag.provider_name` | `name` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. |
57+
| Log Record Attribute | Provider Metadata Field | Requirement level | Notes |
58+
| ---------------------------- | ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
59+
| `feature_flag.provider_name` | `name` | `Recommended` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. |
60+
61+
## Footnotes
62+
63+
[^1]: Include if and only if an error occurred during a flag evaluation.
64+
[^2]: The `variant` field is required if the `value` field is not set.
65+
[^3]: The `value` field is required if the `variant` field is not set.
66+
67+
[otel-ff-logs]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/

0 commit comments

Comments
 (0)