split_clients în Nginx

split_clients "șir" $variabila {
    procent%  valoare;
    ...
    *         valoare;
}

Ce face split_clients

split_clients calculează un hash (MurmurHash2) din șirul dat, de exemplu IP-ul clientului sau un cookie, și pune rezultatul într-unul din grupurile definite prin procente. Variabila primește valoarea grupului. Același șir ajunge mereu în același grup, deci un vizitator vede aceeași variantă la fiecare vizită.

Procentele se adună de sus în jos; * prinde restul. Dacă suma lor este sub 100% și nu există *, clienții rămași primesc o valoare goală.

Directiva se scrie în blocul http. Valoarea se folosește apoi în root, proxy_pass (cu un upstream pentru fiecare variantă), add_header sau jurnale.

Parametri

Parametru	Descriere
Context	http.
"șir"	Textul din care se calculează hash-ul, de obicei cu variabile: "${remote_addr}${http_user_agent}".
procent%	Procentul de clienți care primesc valoarea; poate avea zecimale (0.5%).
*	Toți clienții rămași.

Ce returnează

Variabila definită primește valoarea grupului clientului.

Exemple

Exemplul 1: Test A/B: 20% din vizitatori văd pagina nouă

Directoarele /var/www/exemplu.ro/noua și /var/www/exemplu.ro/veche conțin cele două variante.

split_clients "${remote_addr}pagina-noua" $varianta_pagina {
    20%  noua;
    *    veche;
}

server {
    # ...
    location = / {
        root /var/www/exemplu.ro/$varianta_pagina;
        add_header X-Varianta $varianta_pagina;
    }
}

Exemplul 2: Lansare treptată (canary) pentru 5% din utilizatori

Hash-ul folosește id-ul utilizatorului din cookie, așa că aceeași persoană rămâne pe aceeași versiune, indiferent de IP.

upstream aplicatie_v1 { server 10.0.0.11:8080; }
upstream aplicatie_v2 { server 10.0.0.12:8080; }

split_clients "${cookie_utilizator_id}" $versiune {
    5%   aplicatie_v2;
    *    aplicatie_v1;
}

server {
    # ...
    location / {
        proxy_pass http://$versiune;
    }
}

Greșeli frecvente

• Folosești doar $remote_addr: toți angajații dintr-o firmă (același IP public) ajung în același grup. Combină cu un cookie sau cu $http_user_agent.
• Pui split_clients într-un server sau location: nginx -t spune că directiva nu este permisă acolo ("split_clients" directive is not allowed here).