Skip to content

Commit 6c673d7

Browse files
toddbaerttoddbaert
authored
feat: add appendix D (observability) (#287)
- adds small appendix section to spec that defines how particular SDK fields are mapped to the recently merge OTel semantics - this allows providers and hooks to export OTel data consistently for easy interop - adds a couple supporting glossary liks --------- Signed-off-by: Todd Baert <[email protected]>
1 parent c287b58 commit 6c673d7

File tree

3 files changed

+65
-0
lines changed

3 files changed

+65
-0
lines changed

‎specification/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,11 @@ sidebar_position: 0
1616
- [Evaluation Context](./sections/03-evaluation-context.md)
1717
- [Hooks](./sections/04-hooks.md)
1818
- [Events](./sections/05-events.md)
19+
- [Tracking](./sections/06-tracking.md)
1920
- [Appendix A: Included Utilities](./appendix-a-included-utilities.md)
2021
- [Appendix B: Gherkin Suites](./appendix-b-gherkin-suites.md)
22+
- [Appendix C: OFREP](./appendix-c-ofrep.md)
23+
- [Appendix D: Observability](./appendix-d-observability.md)
2124

2225
## Conformance
2326

‎specification/appendix-d-observability.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
id: appendix-d
3+
title: "Appendix D: Observability"
4+
description: Conventions for OpenFeature telemetry signals
5+
sidebar_position: 5
6+
---
7+
8+
# Appendix D: Observability
9+
10+
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.
12+
13+
## Evaluations
14+
15+
Flag evaluation telemetry comprises data resolved from the provider resolution (evaluation details and flag metadata) as well as metadata about the provider itself.
16+
This is particularly relevant to telemetry-related [hooks](./sections/04-hooks.md).
17+
18+
### Evaluation Details
19+
20+
The following describes how fields on the [evaluation details](types.md#evaluation-details) are mapped to feature flag log records:
21+
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/)).
33+
> OpenFeature [error codes](types.md#error-code) and [resolution reasons](./types.md#resolution-reason) should be transformed accordingly by integrations which include this data.
34+
35+
#### Flag Value
36+
37+
The flag value is required if the `feature_flag.variant` is not set (and optional otherwise), and is defined in a the event body:
38+
39+
| Body Field | Source Field from Evaluation Details | Notes |
40+
| ---------- | ------------------------------------ | ------------------------------------------- |
41+
| `value` | `value` | The type of the `value` field is undefined. |
42+
43+
### Flag Metadata
44+
45+
The following describes how keys in [flag metadata](types.md#flag-metadata) are mapped to feature flag log records:
46+
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). |
52+
53+
> [!NOTE]
54+
> Keys in flag metadata use the "camelCase" casing convention, while the OpenTelemetry standard uses a namespaced "snake_case" convention.
55+
56+
### Provider Metadata
57+
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`. |

‎specification/types.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ A structure which contains a subset of the fields defined in the `evaluation det
5858
- variant (string, optional)
5959
- flag metadata ([flag metadata](#flag-metadata), optional)
6060

61+
#### Resolution Reason
62+
6163
A set of pre-defined reasons is enumerated below:
6264

6365
| Reason | Explanation |

0 commit comments

Comments
 (0)