Metrics : Conception de l'instrumentation

Les labels des métriques sont validés et limités avant ingestion à l'aide de budgets de cardinalité par métrique, préservant les chemins de débogage à haute cardinalité sans laisser des tags non bornés exploser les coûts de stockage ou de requête.

Statut du package : Package de référence assisté par IA. La validation statique du package est passée ; les scénarios d’implémentation restent à exécuter et une revue humaine du domaine est requise avant adoption stable.

Décision

Les labels à haute cardinalité sont contrôlés au moment de l’ingestion avec des budgets par métrique plutôt qu’après une explosion des coûts de stockage. Chaque famille de métriques déclare les labels autorisés, le nombre maximal de séries distinctes, ainsi que le comportement de suppression ou d’agrégation lorsque les budgets sont dépassés. La capacité de débogage est préservée via des issues d’échappement intentionnelles — sessions de débogage limitées ou métriques diagnostiques dédiées à faible rétention — et non en autorisant des ids utilisateur ou ids de requête non bornés sur les chemins critiques. La validation des labels rejette les tags inconnus ou mal formés avant qu’ils n’entrent dans le backend de séries temporelles.

Portée

• Listes blanches de labels et compteurs de cardinalité par nom de métrique.
• Application côté ingestion, règles de suppression, et compteurs de suppression visibles par l’opérateur.
• Canaux de dérogation de débogage avec TTL et approbation pour capture temporaire à haute cardinalité.
• Tableaux de bord et alertes sur l’utilisation des budgets et les séries supprimées.
• Guide pour les développeurs sur la conception sécurisée des labels pour la nouvelle instrumentation.

Hors de ce périmètre

• Cardinalité dans les pipelines de logs (voir bloc journalisation structurée).
• Politiques d’échantillonnage en queue de trace.
• Négociations de facturation avec les fournisseurs.

Contrat

• Chaque métrique sur chemin critique déclare un budget de cardinalité avant activation de l’ingestion en production.
• Les labels sont validés avant ingestion ; les labels inconnus sur les métriques budgétisées sont supprimés ou rejetés selon le profil.
• Le dépassement de budget incrémente un compteur visible cardinality_drop_total et ne rejette jamais silencieusement l’ensemble du flux métrique sans audit.
• Les dérogations de débogage requièrent un identifiant de ticket, une date d’expiration, et une expiration automatique ; elles ne peuvent pas augmenter de façon permanente les budgets des chemins critiques.
• Les ids utilisateur, adresses email et URLs brutes sont interdits comme valeurs de labels sur les métriques budgétisées.
• Le label d’overflow agrégé route_template=cardinality_overflow préserve les tableaux de bord SLO lorsque le détail est supprimé ; le même nom et valeur de label d’overflow sont utilisés dans tous les fixtures et chemins d’application.
• Les changements de configuration de budget sont versionnés et prennent effet sans redémarrage des processus applicatifs lorsque possible.

Conseils d’implémentation

• Implémenter l’application dans les agents ou récepteurs, pas seulement dans la documentation.
• Exposer les comptes de séries par métrique aux propriétaires de service chaque semaine.
• Associer les événements de suppression de labels avec des identifiants de corrélation de logs structurés uniquement en mode débogage.

Gestion des erreurs et protections

• Si le contrôleur de cardinalité est indisponible, par défaut supprimer les labels inconnus plutôt qu’accepter tous les tags.
• Les augmentations d’urgence de budget nécessitent un lien vers un ticket, une date d’expiration, et une expiration automatique ; les dérogations expirées sont annulées sans redéploiement.
• Ne pas supprimer les labels requis pour les métriques d’audit légalement obligatoires sans revue de conformité.

Vérification et exploitation

• Suivre l’utilisation des budgets, le taux de séries supprimées, et l’usage des dérogations de débogage.
• Tester la charge d’ingestion avec des explosions synthétiques de labels pour vérifier la latence d’application.
• Exécuter les scénarios d’acceptation dans le dépôt cible ; les scénarios packagés ne constituent pas une preuve d’exécution.

Hypothèses d’adoption

• Les seuils dans example.yaml et metric-budget.yaml sont des choix de profil, pas des valeurs par défaut universelles.
• Les équipes cartographient les registres de métriques et la propriété à leur stack d’observabilité.

Références

• prometheus-label-practices