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

ステータス: Development

背景

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

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

評価の記録

フィーチャーフラグの評価は、Loggerのemit操作に渡されるEventの属性として記録されるべきです（SHOULD）。

[!NOTE] イベントは開発中であり、一部の言語ではまだ利用できません。対応する言語での実装状況は、spec-compliance matrixを確認してください。

評価イベント

次の表は、Eventに追加すべき属性とその型を示しています。

Status:

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

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

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

Attributes:

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

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

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

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

[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`	計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。

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

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