<!-- review: finished -->

<a id="http-split-clients"></a>

# Split Clients

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

<a id="configuration-example-40"></a>

## Configuration Example

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

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

<a id="directives-43"></a>

## Directives

<a id="index-0"></a>

<a id="id1"></a>

### split_clients

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `split_clients` string $variable { ... }   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                       |

Creates a $variable by hashing the string;
variables in the string are substituted,
the result is hashed,
then the hash value is used to select the string value of the $variable.

The hash function uses
[MurmurHash2](https://en.wikipedia.org/wiki/MurmurHash#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 don't fall into other buckets are mapped to its assigned value.

Example:

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

Here, after substitution in the `$*remote_addr*AAA` 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 `""`
  (empty string).