Objectifs SLO par groupe d'opérations

Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la capacité côté produit : guide produit ; l'appeler : guide développeur.

Pourquoi - une équipe ne raisonne pas qu'opération par opération : elle promet une disponibilité par service (« l'API des évènements : 99,5 % »), tient quelques opérations critiques, suit des parcours (« s'inscrire », « payer ») et affiche un chiffre de tête. Depuis 1.6.0, un objectif se déclare sur un groupe d'opérations, dans le même fichier slos que ceux d'une opération : un budget, un burn rate et une alerte slo-burn pour le groupe, au lieu de vingt budgets sans vue d'ensemble. Rien ne change à la passerelle : aucune série, aucun label, aucune extension x-flexway-* de plus - la console lit les séries existantes avec un filtre sur operation.

Pas encore complet - les objectifs de groupe sont servis : déclaration, calcul dans les deux sources de métriques, alerte slo-burn, écrans de la console, couverts par les tests unitaires et de contrat. Restent, sans version annoncée : la preuve de bout en bout qu'un groupe brûle sous une panne injectée et que l'alerte arrive, et la mesure du coût d'évaluation. D'ici là, le plafond de 100 objectifs est provisoire.

# Valeurs de la console
slos:
  # 1.5.0, inchangé : une opération critique (son identifiant est l'operationId)
  - operation: createOrder
    latency: { p95: 300ms, target: 99% }
  # Un service : toutes les opérations dont x-flexway-upstream nomme cet amont
  - name: events-api
    upstream: events-svc
    availability: 99.5%
  # Une étiquette OpenAPI (tags de l'opération), moins une sonde
  - name: results
    tag: results
    exclude: [healthz]
    availability: 99%
  # Un parcours : une liste explicite, la latence jugée sur chaque étape
  - name: register
    operations: [createAccount, verifyEmail, createProfile]
    availability: 99.5%
    latency: { p95: 800ms, target: 99%, per: member }
  # Le chiffre de tête : toutes les opérations servies, intégrées comprises (ai.*)
  - name: global
    all: true
    exclude: [healthz]
    availability: 99.9%
    window: 30d

Clé	Règle	Défaut
Sélecteur	Exactement un par entrée : operation, ou name et upstream, tag, operations ou all: true - zéro ou deux refusent le fichier	-
name	Obligatoire pour un groupe, interdit avec operation ; [a-z0-9][a-z0-9-]{0,62}, unique parmi les noms et les opérations déclarées	-
upstream	Un amont de upstreams de flexway.yaml : ses opérations déclarées (x-flexway-upstream), jamais le label upstream des séries - un succès du cache y compte sous _none	-
tag	Une étiquette OpenAPI ; une méthode gRPC n'en a pas	-
operations	2 à 50 operationId sans doublon ; une seule s'écrit operation	-
all	true seulement : toutes les opérations servies, ai.* comprises	-
exclude	Avec upstream, tag ou all : 50 operationId au plus retirés du groupe (sondes, administration)	aucun
latency.per	group : le p95 du groupe (seaux additionnés) ; member : chaque membre ayant du trafic, le plus lent juge la minute	group
window	1 à 90 j	30d
Plafond	100 objectifs, un par signal déclaré ; un groupe compte pour un - provisoire tant que le coût d'évaluation n'est pas mesuré	100

Comment c'est calculé - la disponibilité d'un groupe est pondérée par les requêtes (1 - Σ 5xx / Σ réponses sur tous ses membres) : un membre à fort volume pèse ce que vivent ses requêtes, un membre sans trafic ne compte ni pour ni contre. La latence est la part des minutes où le p95 tient la cible - celui du groupe, ou celui du membre le plus lent avec per: member. Budget, burn rate (1 h, 6 h, 3 j) et seuils de slo-burn sont ceux d'un objectif d'opération. Les membres sont ceux d'aujourd'hui sur toute la fenêtre : une opération ajoutée au contrat sous l'étiquette entre dans le groupe au rechargement suivant de /config (journal console.alert.slo_members_changed), sans historique avant elle. Un parcours mesure ses requêtes, jamais le produit des disponibilités de ses étapes : fixez la cible en conséquence.

À l'écran - Trafic, onglet Objectifs (SLO) : les objectifs par niveau (global, services, parcours, opérations), une ligne ouvre le panneau de l'objectif - qui consomme le budget (part de chaque membre), membres et dernier changement, déclaration, « Créer une alerte ». La Vue d'ensemble porte l'objectif all en tête ; l'écran Opération liste les groupes dont elle est membre. Admins seulement : un objectif se calcule sur tous les tenants (403 avant toute lecture pour un lecteur).

Alerter - slo-burn couvre déjà chaque groupe ; ses sujets sont les identifiants d'objectif (l'operationId, ou le name d'un groupe). Pour notifier d'autres webhooks pour un objectif :

alerts:
  rules:
    - { name: checkout-burn, kind: slo_burn, objective: register, notify: [ops-pager] }

Compatibilité - un fichier de 1.5.0 se charge à l'identique. Deux changements assumés, dans les notes de version : une entrée operation qui nomme une opération absente de /config est désormais refusée au chargement d'un fichier changé (elle était acceptée et jamais calculée) ; dans les webhooks, target.kind de slo-burn vaut objective et chaque entrée slos[] d'un résumé porte objective, operation valant null pour un groupe - un consommateur strict doit accepter ce null.

Symptôme	Cause	Que faire
Écran Alertes ou Objectifs : Dernière version du fichier refusée avec upstream ... is not in the gateway's configuration	Le fichier changé nomme un amont, une étiquette ou une opération que la passerelle ne sert pas	Corriger le nom ou déployer d'abord la passerelle ; la version précédente s'applique d'ici là
Un objectif Invalide, en bandeau	La configuration de la passerelle a changé sous un fichier accepté (amont retiré, opération renommée), ou le groupe est vide après exclude	Corriger slos ou rétablir ce qu'il nomme ; l'objectif n'est jamais calculé sur un groupe amputé
the group has no operation once exclude is applied	exclude retire tous les membres	Réduire exclude
a group's name is an operation's too	Un name égal à un operationId déclaré	Renommer le groupe
L'objectif global ne bouge pas malgré une panne d'une opération	Elle pèse peu dans le volume : la disponibilité est pondérée par les requêtes	Lire la part de chaque membre dans le panneau, et déclarer un objectif sur l'opération ou un groupe plus étroit
Rien en tête de la Vue d'ensemble	Aucun objectif all: true, ou session d'un lecteur	Déclarer un objectif global ; un lecteur ne le voit jamais