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.

When building from the source code, the module is built by default together with the Stream module (enabled with --with-stream); it can be disabled with the build option --without-stream_split_clients_module.

In packages and images from our repositories, the module is included in the build.

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)