Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
beeme1mr merged 3 commits into from
Sep 25, 2025
Merged

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

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
17c7ec9
chore: update references from log to event, clarify value requirement…
beeme1mr Sep 15, 2025
7f3ac58
Update specification/appendix-d-observability.md
beeme1mr Sep 16, 2025
5331113
Merge branch 'main' into include-value-in-observablity
beeme1mr Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions specification/appendix-d-observability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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) |
Expand All @@ -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). |
Expand All @@ -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 |
| --------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------- |
Expand All @@ -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/
Comment thread
beeme1mr marked this conversation as resolved.
Loading