<!-- review: finished -->

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

# 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.

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

## Configuration Example

```nginx
stream {
    # ...
    split_clients "${remote_addr}AAA" $upstream {
                  0.5%                feature_test1;
                  2.0%                feature_test2;
                  *                   production;
    }

    server {
        # ...
        proxy_pass $upstream;
    }
}
```

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

## Directives

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

<a id="s-split-clients"></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)  | 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](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 appear at the end;
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 `""`
  (an empty string)