stream_split_clients
module#
The module emits variables for A/B testing, canary releases, or other scenarios that require routing a percentage of clients to one server or configuration while directing the rest elsewhere.
Example Configuration#
stream {
# ...
split_clients "${remote_addr}AAA" $upstream {
0.5% feature_test1;
2.0% feature_test2;
* production;
}
server {
# ...
proxy_pass $upstream;
}
}
Directives#
split_clients#
- Syntax:
split_clients
string $variable { … }- Default:
—
- Context:
stream
Creates a $variable by hashing the string; the variables in string are substituted, the result is hashed, then the hash is mapped to the $variable’s string value.
The hash function uses
MurmurHash2
(32-bit),
and its entire value range
(0 to 4294967295)
is mapped to buckets in order of appearance;
the percentages determine the size of the buckets.
A wildcard (*
) may occur last;
hashes that fall outside other buckets are mapped to its assigned value.
An example:
split_clients "${remote_addr}AAA" $variant {
0.5% .one;
2.0% .two;
* "";
}
Here, the hashed values of the interpolated ${remote_addr}AAA string are distributed as follows:
values 0 to 21474835 (a sample of 0.5%) yield .one
values 21474836 to 107374180 (a sample of 2%) yield .two
values 107374181 to 4294967295 (all other values) yield “” (an empty string)