Split Clients#

The module generates variables for A/B testing, canary releases, and other scenarios that route a specific percentage of clients to one server or configuration while directing the rest elsewhere.

Configuration Example#

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; variables in the string are substituted, the result is hashed, and the hash value is used to select the string value of the $variable.

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 appear at the end; hashes that don't fall into other buckets are mapped to its assigned value.

Example:

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

Here, after substitution in the $remote_addrAAA string, the hash values are distributed as follows:

  • values from 0 to 21474835 (0.5%) yield .one

  • values from 21474836 to 107374180 (2%) yield .two

  • values from 107374181 to 4294967295 (all others) yield "" (an empty string)