> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/feature-flags/feature-flags-events/


# イベント内のフィーチャーフラグに関するセマンティック規約

**ステータス**: [Development][DocumentStatus]

## 背景

フィーチャーフラグは、機能のリリースをデプロイから分離するために、現代的なアプリケーションで一般的に使われています。多くのフィーチャーフラグツールは、リモートのフィーチャーフラグ管理サービスからほぼリアルタイムでフラグの設定を更新する機能をサポートしています。また、コンテキスト情報に基づいて値を返すルールセットを定義できることも一般的です。たとえば、コンテキスト（ユーザーのメールドメイン、会員ランク、国など）に基づいて、特定のユーザーのサブセットのみに機能を有効化する、といった使い方があります。

フィーチャーフラグは動的であり、実行時の挙動に影響を与えるため、関連するフィーチャーフラグのテレメトリーシグナルを収集することが重要です。これは、A/Bテストや段階的な機能リリースといった高度なオブザーバビリティのユースケースを可能にする、機能がリクエストに与える影響の判定に使えます。

## 評価の記録

フィーチャーフラグの評価は、[Logger](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/specification/logs/api.md#logger)のemit操作に渡される[Event](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/specification/logs/data-model.md#events)の属性として記録されるべきです（SHOULD）。

> [!NOTE]
> イベントは開発中であり、一部の言語ではまだ利用できません。対応する言語での実装状況は、[spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/spec-compliance-matrix.md#logs)を確認してください。

## 評価イベント

次の表は、[Event](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/specification/logs/data-model.md#log-and-event-record-definition)に追加すべき属性とその型を示しています。

<!-- semconv event.feature_flag.evaluation -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid)

イベント名は`feature_flag.evaluation`でなければなりません（MUST）。

フィーチャーフラグの評価をイベントとして定義します。

`feature_flag.evaluation`イベントは、フィーチャーフラグの値が評価されるたびに発行されるべきです（SHOULD）。これはアプリケーションのライフサイクルの中で何度も発生する可能性があります。たとえば、異なるアニメーションをA/Bテストするウェブサイトは、ボタンがクリックされるたびにフラグを評価する場合があります。`feature_flag.evaluation`イベントは、結果が同じであっても評価ごとに発行されます。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`feature_flag.key`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | フィーチャーフラグのルックアップキー。 | `logo-color` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | 操作が終了したエラーのクラスを記述します。[2] | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` |
| [`feature_flag.result.value`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` [3] | any | フィーチャーフラグの評価済みの値。[4] | `#ff0000`; `true`; `3` |
| [`feature_flag.result.variant`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` [5] | string | 評価されたフラグ値に対する意味的な識別子。[6] | `red`; `true`; `on` |
| [`feature_flag.context.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | フラグ評価コンテキストの一意な識別子。たとえばターゲティングキー。 | `5157782b-2203-4c80-a857-dbbd5e7761db` |
| [`feature_flag.error.message`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` [7] | string | フィーチャーフラグの評価中に発生したエラーについて、人間が読める形式でより詳細を提供するメッセージ。[8] | `Unexpected input type: string`; `The user has exceeded their storage quota` |
| [`feature_flag.provider.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | フィーチャーフラグのプロバイダーを識別します。 | `Flag Manager` |
| [`feature_flag.result.reason`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | フィーチャーフラグの値がどのように決定されたかを示す理由コード。 | `static`; `targeting_match`; `error`; `default` |
| [`feature_flag.set.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | フィーチャーフラグが属する[フラグセット](https://openfeature.dev/specification/glossary/#flag-set)の識別子。 | `proj-1`; `ab98sgs`; `service1/dev` |
| [`feature_flag.version`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/feature-flag/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | 評価に使われたルールセットのバージョン。ルールセットを一意に識別する安定した値であれば何でもかまいません。 | `1`; `01ABCDEF` |

**[1] `error.type`:** フラグの評価中にエラーが発生した場合に限ります。

**[2] `error.type`:** 次の値のいずれかが該当する場合は、それを使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `flag_not_found` | フラグが見つかりませんでした。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `invalid_context` | 評価コンテキストがプロバイダーの要件を満たしていません。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `parse_error` | フラグ設定などのデータを解析する際にエラーが発生しました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `provider_fatal` | プロバイダーが回復不能なエラー状態に陥りました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `provider_not_ready` | プロバイダーが初期化される前に値が解決されました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `targeting_key_missing` | プロバイダーがターゲティングキーを要求しているにもかかわらず、評価コンテキストに指定されていませんでした。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `type_mismatch` | フラグ値の型が期待される型と一致しません。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `general` | 上記に列挙されていない理由によるエラーです。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |

**[3] `feature_flag.result.value`:** フィーチャーフラグのプロバイダーがvariantまたは同等の概念を提供しない場合に限ります。それ以外の場合、`feature_flag.result.value`はopt-inとして扱われるべきです（should）。

**[4] `feature_flag.result.value`:** 一部のフィーチャーフラグプロバイダーでは、フィーチャーフラグの評価結果が非常に大きくなったり、非公開または機微な詳細を含んだりすることがあります。
このため、利用可能であれば`feature_flag.result.variant`のほうが好ましい属性であることが多いです。

可能であれば、`feature_flag.result.value`を削除したり、そのサイズや範囲を制限したりすることが望ましい場合があります。評価済みのフラグ値は非構造化データであり、どのような型にもなりうるため、これをどのように達成するのが最善かは計装の実装者に委ねられます。

**[5] `feature_flag.result.variant`:** フィーチャーフラグのプロバイダーがvariantまたは同等の概念を提供する場合。

**[6] `feature_flag.result.variant`:** 一般にvariantと呼ばれる意味的な識別子は、値そのものを含めずに値を参照する手段を提供します。これは、値の背後にある意味を理解するための追加のコンテキストを提供できます。たとえば、値`#c05543`に対してvariant `red`が使われることがあります。

**[7] `feature_flag.error.message`:** フラグの評価中にエラーが発生し、かつ`error.type`だけではエラーを十分に説明できない場合に限ります。

**[8] `feature_flag.error.message`:** `error.type`の値を単純に複製するのではなく、より多くのコンテキストを提供すべきです（should）。たとえば、`error.type`が`invalid_context`である場合、`feature_flag.error.message`はどのコンテキストキーが欠落しているか、または無効であるかを列挙してもかまいません。

---

`error.type`には、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

---

`feature_flag.result.reason`には、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `cached` | 解決された値はキャッシュから取得されました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `default` | 解決された値は、事前に設定された値にフォールバックしました（動的評価が発生しなかった、または動的評価が結果を返さなかった）。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `disabled` | 解決された値は、管理システムでフラグが無効化されていた結果です。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `error` | 解決された値は、エラーの結果です。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `split` | 解決された値は、疑似ランダムな割り当ての結果です。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `stale` | 解決された値は非権威的であるか、期限切れの可能性があります。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `static` | 解決された値は静的です（動的評価なし）。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `targeting_match` | 解決された値は、ルールや特定のユーザーターゲティングなどの動的評価の結果です。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `unknown` | 解決された値の理由を判定できませんでした。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status