Abortar automaticamente um rollout quando a taxa de erro estourar o limite

Um guardrail observa uma métrica em relação a um rollout em andamento e age sobre ela sem precisar de uma decisão humana no momento. Este tutorial anexa um guardrail que aborta um rollout se a taxa de erro passar de 5%, e depois mostra como ver o que ele decidiu e por quê.

1. Anexe um guardrail a um rollout agendado ou ativo

POST /v1/rollouts/{rollout_id}/guardrails exige que o rollout esteja scheduled ou active (a chamada é rejeitada depois que o rollout já completou ou foi abortado), e que a definição de métrica referenciada pertença ao mesmo projeto da configuração de flag do rollout:

const res = await fetch(
  `https://api.rollfuse.com/v1/rollouts/${rolloutId}/guardrails`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      metric_definition_id: errorRateMetricId,
      comparison_operator: "gt",
      threshold: 0.05,
      evaluation_window_seconds: 300,
    }),
  }
);
const guardrail = await res.json();
console.log(guardrail.id, guardrail.comparison_operator, guardrail.threshold);

comparison_operator é um entre gt, gte, lt, lte. Esse guardrail lê o seguinte: a cada janela de 300 segundos, se a métrica de taxa de erro for maior que 0,05, aja sobre isso. evaluation_window_seconds controla quanto de dado cada checagem observa, então um pico mais curto que a janela não necessariamente dispara o guardrail sozinho.

2. O que o guardrail faz automaticamente

Uma vez anexado, o guardrail é avaliado de forma recorrente contra observações novas da sua métrica, sem nenhuma ação adicional da sua parte. Dependendo do que observa, ele pode produzir um destes resultados sobre o rollout: rollout_aborted, rollout_paused, rollout_resumed ou rollout_promoted (avançando após um estágio saudável), além de none quando nada muda. É a violação do limite que dispara rollout_aborted ou rollout_paused, não algo que você chama manualmente; ainda assim você pode chamar POST /v1/rollouts/{rollout_id}/abort ou .../pause por conta própria se quiser agir antes do guardrail.

Você pode listar todos os guardrails de um rollout com GET /v1/rollouts/{rollout_id}/guardrails, e buscar um específico por id com GET /v1/rollouts/{rollout_id}/guardrails/{guardrail_id}.

3. Consulte o histórico de avaliações do guardrail

Cada checagem que o guardrail faz fica registrada como uma PolicyEvaluation. Liste-as com GET /v1/rollouts/{rollout_id}/guardrails/{guardrail_id}/policy-evaluations, ordenadas da mais antiga para a mais recente:

const historyRes = await fetch(
  `https://api.rollfuse.com/v1/rollouts/${rolloutId}/guardrails/${guardrail.id}/policy-evaluations`,
  { headers: { Authorization: `Bearer ${token}` } }
);
const { policy_evaluations } = await historyRes.json();

for (const evaluation of policy_evaluations) {
  console.log(
    evaluation.evaluated_at,
    evaluation.observed_value,
    evaluation.breached,
    evaluation.action, // "none" | "rollout_aborted" | "rollout_paused" | "rollout_resumed" | "rollout_promoted"
    evaluation.reason
  );
}

observed_value é o valor da métrica naquela janela, breached indica se ela ultrapassou o threshold, e reason explica casos de borda em linguagem simples, por exemplo dados insuficientes na janela, ou um guardrail irmão no mesmo rollout já ter abortado o rollout naquele mesmo ciclo.

Próximo passo

Um guardrail só enxerga dados do rollout ao qual está anexado; se você ainda não agendou o rollout, comece pelo tutorial de rollout percentual, e anexe o guardrail antes, ou logo depois, do primeiro estágio do rollout entrar no ar.