Split Clients#

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.

Configuration Example# 

http {
    split_clients "${remote_addr}AAA" $variant {
                   0.5%               .one;
                   2.0%               .two;
                   *                  "";
    }

    server {
        location / {
            index index${variant}.html;

Directives#

split_clients#

Syntax

split_clients string $variable { ... }

Default

—

Context

http

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_addrAAA 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)