open-feature
/
spec
mirror of https://github.com/open-feature/spec.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

chore: rename from log to event, clarify value requirements (#341) 

Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com>
This commit is contained in:
Michael Beemer 2025-09-25 12:51:13 -04:00 committed by GitHub
parent ece8b7ce04
commit 25dac91f8a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 11 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
specification/appendix-d-observability.md
View File

@ -1,14 +1,14 @@
---
id: appendix-d
title: "Appendix D: Observability"
description: Conventions for OpenFeature telemetry signals
description: Conventions for OpenFeature telemetry signals
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][otel-ff-logs] and other semantic conventions.
It primarily focuses on providing recommendations for mapping well-known fields in OpenFeature to [OpenTelemetry feature-flag event records][otel-ff-events] and other semantic conventions.
## Evaluations
@ -17,9 +17,9 @@ This is particularly relevant to telemetry-related [hooks](./sections/04-hooks.m
### Evaluation Details
The following describes how fields on the [evaluation details](types.md#evaluation-details) are mapped to feature flag log records:
The following describes how fields on the [evaluation details](types.md#evaluation-details) are mapped to feature flag event records:
| Log Record Attribute | Source Field or Derived Value from Evaluation Details | Requirement level | Type | Notes |
| Event 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) |
@ -29,14 +29,14 @@ The following describes how fields on the [evaluation details](types.md#evaluati
| `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]).
> The `error.type` and `feature_flag.result.reason` enumerations use a lowercase "snake_case" convention (see [OpenTelemetry feature-flag event records][otel-ff-events]).
> 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 Metadata
The following describes how keys in [flag metadata](types.md#flag-metadata) are mapped to feature flag log records:
The following describes how keys in [flag metadata](types.md#flag-metadata) are mapped to feature flag event records:
| Log Record Attribute | Flag Metadata Key | Requirement level | Type | Notes |
| Event 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). |
@ -47,14 +47,14 @@ The following describes how keys in [flag metadata](types.md#flag-metadata) are
### Provider Metadata
| Log Record Attribute | Provider Metadata Field | Requirement level | Type | Notes |
| Event 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
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.
The following table describes the history of changes to the OpenTelemetry feature flag event records as it progresses towards a stable release.
| Original Field Name | New Field Name | Semantic Convention Release |
| --------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------- |
@ -67,7 +67,7 @@ The following table describes the history of changes to the OpenTelemetry featur
## Footnotes
[^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.
[^2]: The `value` field is required when a `variant` is not available, and recommended when it is. Considerations should be made for large and/or sensitive values, which 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/
[otel-ff-events]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/