Skip to content

Latest commit

 

History

History
67 lines (47 loc) · 5.91 KB

appendix-d-observability.md

File metadata and controls

67 lines (47 loc) · 5.91 KB
id title description sidebar_position
appendix-d
Appendix D: Observability
Conventions for OpenFeature telemetry signals
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 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

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