パーセンテージロールアウト

パーセンテージロールアウトでは、機能を一部のユーザーへ段階的に公開できます。どの ターゲティングルール にも、0 から 100 のロールアウト割合を指定できます。

影響範囲を抑えたいとき、実験を回したいとき、新しいコードをデプロイせずにリクエストをサンプリングしたいときに使います。

ルールにパーセンテージロールアウトがある場合、ルール条件とロールアウトバケットの両方が一致したときだけ、そのバリアントを返します。ルールに一致しないコンテキストは次のルールへ進み、以降のルールにも一致しなければデフォルトバリアントを受け取ります。

たとえば、enterprise プランのユーザーを対象にし、そのうち 10% だけに新しい体験を返すルールを作れます。残りの 90% は、ルール一覧の続きへ進みます。

{
	"priority": 1,
	"conditions": [
		{ "attribute": "plan", "operator": "equals", "value": "enterprise" }
	],
	"serve_variation": "on",
	"rollout": {
		"percentage": 10,
		"attribute": "userId"
	}
}

パーセンテージロールアウトがバリアントを返したとき、評価 details の reason は SPLIT です。

Flagship は、設定可能な属性に対する一貫したハッシュで、ユーザーをロールアウトバケットに割り当てます。同じロールアウト設定では、同じユーザーは常に同じフラグ値を受け取ります。繰り返し評価しても、体験は一貫します。

デフォルトのバケット属性は targetingKey です。ダッシュボードでロールアウトを設定するとき、バケットに使う属性を選べます。

ロールアウトバケットは、アカウントとフラグごとに独立しています。同じ識別子でも、フラグが違えば別のバケットに入ることがあります。無関係な機能どうしでロールアウトが連動するのを避けられます。

何を安定させたいかに応じて、バケット属性を選びます。

機能リリースや実験では、安定したユーザーまたはアカウントの識別子を使ってください。リクエストごとに変わってよい場合（トラフィックサンプリングなど）にだけ、リクエスト単位の値を使います。

小さなロールアウトから始め、アプリケーションを監視し、信頼が高まったらパーセンテージを上げます。

1. 5% のロールアウトでフラグを作成します。
2. エラー、レイテンシ、プロダクト指標、ユーザーからのフィードバックを監視します。
3. 25%、50%、100% と上げます。
4. ロールアウトが 100% に達したら、一時的なターゲティングルールを削除し、採用したバリアントをデフォルトにします。
5. 機能を完全に出荷したら、古いコードパスを削除し、フラグを削除します。

次のルールを持つフラグ new-checkout を考えます。

1. ルール 1: plan equals "enterprise" — バリアント on を返す。
2. ルール 2: userId に対する 25% ロールアウト — バリアント on を返す。
3. デフォルトバリアント: off。

この構成では次のようになります。

• enterprise ユーザーは全員、新しいチェックアウトを見ます。
• それ以外のユーザーのうち、userId で決まる 25% も新しいチェックアウトを見ます。
• 残りの 75% の非 enterprise ユーザーは、標準のチェックアウトを見ます。

信頼が高まったら、ロールアウト割合を 100% まで上げます。

オーディエンス条件のない単純な A/B/n テストでは、Cloudflare ダッシュボードで各バリアントのトラフィック割合を設定します。累積しきい値はダッシュボードが計算します。

単純な A/B/n テストを API から直接管理する場合は、バリアントごとに 1 つのルールを作り、累積のロールアウト割合を指定します。Flagship はルールを優先度順に評価します。コンテキストがルールに一致しても、そのルールのロールアウト割合に入らなければ、評価は次のルールへ進みます。

バリアント A、B、C を 30% / 40% / 30% で分割する場合:

[
	{
		"priority": 1,
		"conditions": [],
		"serve_variation": "variant-a",
		"rollout": { "percentage": 30, "attribute": "targetingKey" }
	},
	{
		"priority": 2,
		"conditions": [],
		"serve_variation": "variant-b",
		"rollout": { "percentage": 70, "attribute": "targetingKey" }
	},
	{
		"priority": 3,
		"conditions": [],
		"serve_variation": "variant-c",
		"rollout": { "percentage": 100, "attribute": "targetingKey" }
	}
]

API で管理する構成では、最初のルールがバケット 0〜30 を担当します。2 番目のルールはバケット 31〜70 を担当します。最後のルールが残りのバケットを 100 まで拾います。対象となるすべてのコンテキストにバリアントを返す場合は、最後のルールを必ず 100 にします。

実験内のすべてのルールで、同じバケット属性を使ってください。ルールごとに属性が違うと、意図した分割にユーザーが収まらないことがあります。

オーディエンスのターゲティングと、複数バリアントのロールアウトを組み合わせられます。たとえば、premium ユーザーだけを実験に入れ、その premium ユーザーを 3 つのバリアントに分割できます。

ターゲット付き A/B/n テストでは、各バリアントのルールに同じオーディエンス条件を繰り返し、累積のロールアウトしきい値を使います。このターゲット付き複数ルールのパターンでは、ダッシュボードでも API でも、各ルールの累積しきい値を明示的に設定します。

premium ユーザーだけを対象に、20% がバリアント A、40% がバリアント B、残りの 40% がバリアント C を受け取る場合は、しきい値 20、60、100 を使います。

[
	{
		"priority": 1,
		"conditions": [
			{ "attribute": "plan", "operator": "equals", "value": "premium" }
		],
		"serve_variation": "variant-a",
		"rollout": { "percentage": 20, "attribute": "targetingKey" }
	},
	{
		"priority": 2,
		"conditions": [
			{ "attribute": "plan", "operator": "equals", "value": "premium" }
		],
		"serve_variation": "variant-b",
		"rollout": { "percentage": 60, "attribute": "targetingKey" }
	},
	{
		"priority": 3,
		"conditions": [
			{ "attribute": "plan", "operator": "equals", "value": "premium" }
		],
		"serve_variation": "variant-c",
		"rollout": { "percentage": 100, "attribute": "targetingKey" }
	}
]

plan equals "premium" に一致しないユーザーは、3 つのルールをすべてスキップし、以降のルールに一致しなければ、フラグのデフォルトバリアントを受け取ります。

リクエスト単位のバケット属性を選べば、パーセンテージロールアウトをリクエストサンプリングにも使えます。たとえば 1% のロールアウトで、一部のリクエストだけに追加のログや診断を有効にできます。

同じユーザーがリクエストごとに異なる結果を受け取ってよい場合にだけ、このパターンを使ってください。

同じユーザーがリクエストごとに異なる値を受け取る場合、評価コンテキストに targetingKey または設定したバケット属性が欠けている可能性が高いです。

評価のたびに、同じ安定した識別子を渡します。

const enabled = await env.FLAGS.getBooleanValue("gradual-rollout", false, {
	userId: session.user.id,
});

そのうえで、ロールアウトのバケット属性を userId に設定します。

ルールの順序を確認してください。優先度番号が小さいキャッチオールルールがあると、後続のロールアウトルールが実行される前にバリアントを返すことがあります。広いキャッチオールルールは、より具体的なルールのあとに置きます。

ダッシュボードで管理する単純な A/B/n テストでは、各バリアントのトラフィック割合を入力し、しきい値はダッシュボードに計算させます。

API で管理する A/B/n テストや、複数ルールとして設定するターゲット付き A/B/n テストでは、累積しきい値を使います。30% / 40% / 30% の分割では、しきい値は 30、70、100 です。30、40、30 ではありません。

コンテキストがルール条件には一致してもロールアウト割合の外にあり、以降のルールにも一致しない場合に起きます。一致するすべてのコンテキストにデフォルト以外のバリアントを返すなら、後続ルールを追加するか、最後のルールを 100% にしてください。