Função Flags e lançamento de fichas

A função Flag (FF) é uma condição controlada que ativa/desliga o comportamento do sistema sem o lançamento do código. As bandeiras permitem: rolar os fichas de forma segura, apontar grupos de usuários/mercados/tenentes, desativar rapidamente componentes problemáticos, fazer experiências e configurar parâmetros em um rântaim.

• Reduzir a radius blast nos lançamentos.
• Compartilhar implantação e ativação.
• Dê um controle transparente das alterações com áudio, SLO e repasse em um clique.

1) Tipos de bandeiras e quando aplicá-las

Release flags - a inclusão gradual de novos fichas (dark → canary → ramp-up → 100%).
Ops/kill-switch - desativação instantânea de dependências (provedor, subsistema, computação pesada).
Experiment (A/B, multi-variant) - Divisão de tráfego em opções (weights, sticky bucketing).
Permision/Entitlement - Acesso a fichas por papéis/planos/jurisdições.
Remote Config - parâmetros de comportamento (limiar, timeout, fórmula) da bandeira/config.
Migration flags - Alteração de circuitos/caminhos de dados (mudança para novo índice/BD/endpoint).

Anti-pattern, a mesma bandeira «sobre tudo».

2) Modelo de dados de bandeira (mínimo)

yaml flag:
key: "catalog. new_ranker"
type: "release"    # release      ops      kill      experiment      permission      config     migration description: "New Directory Ranking"
owner: "search-team@company"
created_at: "2025-10-01T10:00:00Z"
ttl: "2026-01-31" # delete deadline after 100% enable rules:
- when:
tenant_id: ["brand_eu","brand_latam"]
region: ["EE","BR"]
user_pct: 10 # progressive percentage then: "on"
- when:
kyc_tier: ["unverified"]
then: "off"
variants: # for experiments
- name: "control"; weight: 50
- name: "v1"; weight: 30
- name: "v2"; weight: 20 payload:
v1:
boost_freshness: 0. 3 boost_jackpot:  0. 2 v2:
boost_freshness: 0. 2 boost_jackpot:  0. 4 prerequisites: # dependent flags/schema versions
- key: "catalog. index_v2_ready"
must_be: "on"
audit:
require_ticket: true change_window: "09:00-19:00 Europe/Kyiv"
safeguards:
max_rollout_pct: 50 # stop threshold auto_rollback_on:
p95_ms: ">200"
error_rate: ">2%"

3) Avaliação e meta (evaluation)

Ключи таргетинга: `tenant_id, region/licence, currency, channel, locale, role, plan, device, user_id, cohort, kyc_tier, experiment_bucket`.
Ordem de avaliação: prerequisites → regras deny → regras allow → default.
Sticky bucketing: para experimentar, hasteie um ID estável (por exemplo, «hash (user _ id, flag _ key)») - para que o usuário receba sempre uma opção.

ts result = evaluate(flag, context)  // pure function if (!prereqs_ok(result)) return OFF if (deny_match(result, ctx)) return OFF if (allow_match(result, ctx)) return resolve_variant_or_on(result, ctx)
return flag. default

4) Distribuição e arquitetura FF

• Server-side SDK (recomendado): fontes de verdade e dinheiro no backend; unificação da lógica.
• Edge/CDN evaluação: alvo rápido no perímetro (onde não há PII/segredos).
• Cliente-side SDK: Quando você precisa de personalização UI, mas apenas com um contexto mínimo e sem regras sensíveis.
• Config-as-Código: armazenamento de bandeiras no repositório, validação CI, rollout via CD.

• Startup bootstrap + streaming updates (SSE/gRPC) + fallback para o último snapshot.
• SLA «freshness» bandeiras: p95 ≤ 5 s.

5) Estratégias de lançamento

5. 1 Dark Launch

O Fichá está ativado, mas invisível ao usuário; Coletamos métricas e erros.

5. 2 Canary

Incluímos 1% a 5% do tráfego na mesma jurisdição/tenante; monitor p95/p99, erros, conversão.
Stop conditions - liminares de acionamento automático por métricas.

5. 3 Progressive Rollout

10% → 25% → 50% → 100% no horário de verificação manual/automática.

5. 4 Shadow / Mirroring

Duplicamos as pesquisas para um novo caminho (sem efeito aparente) e comparamos resultados/latência.

5. 5 Blue/Green + FF

Implantando duas versões; a bandeira roda o tráfego e alterna as dependências por segmento.

6) Dependências e consistência cruzada

Use prerequisites e «health bandeiras» prontas: índice construído, migração concluída.
Coordenação através de eventos: 'FlagChanged (flag _ key, scope, new _ state)'.

1. incluir o caminho read → 2) verificar métricas → 3) ativar write/side-effects.

• Contratos de serviço: default deve ser seguro (fail-safe OFF).

7) Observabilidade e SLO

• `flag_eval_p95_ms`, `errors_rate`, `config_freshness_ms`.
• Métricas de negócios: «ctr», «conversion», «ARPU», «retence», guardas (por exemplo, incidentes RG).
• Liminares SLO automáticos para o carro automático.

Logi/trainee: Adicione 'flag _ key', 'variant', 'decision _ fonte' (server/edge/cliente), 'context _ hach'.

Dashboards: «escada» rollout com liminares, heatmap erros por segmento.

8) Segurança e Complacência

Minimização PII no contexto.
RLS/LCA: quem pode mudar quais bandeiras (domínios/mercados).
As janelas do relógio de alteração (mudança windows) e «duplo confirmação» para as bandeiras sensíveis.
Auditoria imutável: quem/quando/quê/porquê (card/invent link).
Jurisdição: as bandeiras não devem contornar proibições regulatórias (por exemplo, incluir o jogo em um país proibido).

9) Controle de bandeiras «de longa vida»

Cada bandeira tem TTL/data de remoção.
Depois de 100% ativado - Crie uma task para remover os galhos de código, ou a «bandeira-dívida» aumenta.
Assinale as bandeiras como 'migration '/' one-time' e separe-as das constantes 'persision/config'.

10) Exemplo de contrato API/SDK

Evaluation API (server-side)

http
POST /v1/flags/evaluate
Headers: X-Tenant: brand_eu
Body: { "keys":["catalog. new_ranker","rgs. killswitch"], "context": { "user_id":"u42", "region":"EE" } }
→ 200
{
"catalog. new_ranker": { "on": true, "variant":"v1", "as_of":"2025-10-31T12:10:02Z" },
"rgs. killswitch":  { "on": false, "variant":null, "as_of":"2025-10-31T12:10:02Z" }
}

Client SDK (кэш, fallback)

ts const ff = await sdk. getSnapshot()     // bootstrap const on = ff. isOn("catalog. new_ranker", ctx)
const payload = ff. payload("catalog. new_ranker", "v1")

11) Interação com outros contornos

Rate limits/quotas: bandeiras podem baixar RPS/incluir trottling na hora do incidente.
Circuito breaker/descradation: kill-switchi desligam caminhos pesados e incluem degradação.
Catálogo/personalização: as bandeiras mudam de peso/regras de classificação (por meio do Remote Config).
Migrações de BD: as bandeiras traduzem progressivamente leitura/gravação para um novo padrão (read-replica → dual-write → write-primary).

12) Playbooks (runbooks)

1. Incidente após inclusão de 25%

O carro automático funcionou → uma bandeira OFF para todos/segmentos, tíquete em on-call, coleta de estações, RCA.
Activar temporariamente a degradação/antigo ramo através da bandeira migração.

2. Crescimento p95 por catálogo

Limiar 'p95 _ ms> 200' - Carro automático; fixar os logs com 'flag _ key = catalog. new_ranker`.
Activar os sinais de classificação simplificados (payload config).

3. Discrepância de jurisdição

A bandeira permisse erroneamente abriu o jogo em 'NL' - OFF + pós-fato auditoria, adição de uma regra guard 'region deny'.

4. Dispersão em A/B

Parar o experimento, executar a análise CUPED/stratied, reencaminhar com a balança atualizada.

13) Testes

Unit: avaliação definida de regras/prioridades/prejulgamentos.
Contract: esquema de bandeiras (JSON/YAML), validadores, verificação CI antes do merjom.
Property-based: «deny> allow», «se», bucketing estável.
Replay: reprodução de contextos reais na nova configuração.
E2E: Cordos canários (step-up/step-down), verificação de automóveis e auditoria de eventos.
Chaos: penhasco de estêncil, desconstrução obsoleta, renovação maciça de bandeiras.

14) Erros típicos

Lógica secreta nas bandeiras de clientes (fuga/troca).
Falta de TTL → «cemitério» bandeiras no código.
Bandeiras «versáteis» sem segmentação → não é possível localizar o problema.
Sem guardrails/carros - incidentes manuais.
Dependências incompatíveis entre as bandeiras → ciclos/raios.
Avaliar as bandeiras em cada solicitação sem o cachê → os destaques de latência.
Falta de auditoria/janela de alterações - riscos de complacência.

15) Folha de cheque antes de vender

• Bandeira criada com tipo, owner, descrição, TTL e exigência de tíquete.
• As regras de targeting são definidas; 'deny' para regiões/papéis indesejados.
• Sticky bucketing está minado; o ID é estável.
• Os adereços e as bandeiras health estão prontos; default seguro.
• Dashboards e alertas em p95/p99, erro _ rate, guardas de negócios.
• O carro automático está configurado; O limiar do rollout e as condições de reversão.
• Plano canário: juros/etapas/janela de alterações/responsáveis.
• Os configs são validados em CI; O sistema está distribuído em clusters/regiões.
• Documentação para suporte/produto; playbooks incidentes.
• Plano de remoção de ramais de código e da própria bandeira após 100%.

16) Exemplo de bandeira «migratória» (BD/índice)

yaml flag:
key: "search. use_index_v2"
type: "migration"
description: "Switching reads to index v2"
prerequisites:
- key: "search. index_v2_built"
must_be: "on"
rules:
- when: { tenant_id: ["brand_eu"], user_pct: 5 } then: "on"
- when: { tenant_id: ["brand_eu"], user_pct: 25 } then: "on"
safeguards:
auto_rollback_on:
search_p95_ms: ">180"
error_rate: ">1%"
ttl: "2026-02-01"

Conclusão

Os Flags não são apenas «ativar/desligar», mas sim uma disciplina de gerenciamento de risco. Os tipos claros de bandeiras, a meta definida, os registos progressivos com guardrails, automóvel, auditoria e plano de remoção tornam os lançamentos previsíveis, e os incidentes são breves e controláveis. Incorporem bandeiras à arquitetura como a primeira classe de cidadãos - e você pode trazer valor com mais frequência, segurança e sentido.