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 and other semantic conventions.

Evaluations

Flag evaluation telemetry comprises data resolved from the provider resolution (evaluation details and flag metadata) as well as metadata about the provider itself. This is particularly relevant to telemetry-related hooks.

Evaluation Details

The following describes how fields on the 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
error.type	error code	Conditionally Required 1	See: 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
feature_flag.evaluation.reason	reason	Recommended	See: reason

Note

The error.type and feature_flag.evaluation.reason enumerations use a lowercase "snake_case" convention (see OpenTelemetry feature-flag log records). OpenFeature error codes and resolution reasons 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	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 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 should be used.
feature_flag.set.id	flagSetId	Recommended	A logical identifier for the flag set.
feature_flag.version	version	Recommended	A version string (format unspecified) for the flag or 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.

Footnotes

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. ↩