OpenTelemetry : maîtriser la cardinalité des métriques de bout en bout
Views du SDK, conventions sémantiques, OpenTelemetry Collector et tail sampling : réduire la cardinalité des métriques et les coûts d'observabilité.
OpenTelemetry rend l'instrumentation facile ; c'est précisément le risque. Ajouter un attribut à une mesure tient en une ligne de code, et chaque attribut ajouté à une métrique multiplie potentiellement le nombre de séries temporelles que le backend doit indexer, garder en mémoire et, souvent, facturer. Un attribut à cent valeurs distinctes peut multiplier par cent le nombre de séries d'une métrique. Un identifiant utilisateur n'a pas de borne du tout.
La cardinalité n'est donc pas un sujet que l'on traite une fois la facture arrivée, quand les coûts d'observabilité ont déjà dérivé. C'est une propriété de l'instrumentation, qui se décide dans le code, se contrôle dans le SDK et se rattrape, en dernier recours, dans l'OpenTelemetry Collector.
Compter avant de couper
La cardinalité d'une métrique est le nombre de combinaisons distinctes de valeurs d'attributs qu'elle produit. Sa borne haute est le produit du nombre de valeurs de chaque attribut. Prenons http.server.request.duration avec 5 méthodes HTTP, 40 routes et 10 codes de statut : jusqu'à 2 000 combinaisons. C'est un histogramme, et les conventions sémantiques lui recommandent 14 bornes de buckets, donc 15 buckets. Converti en histogramme Prometheus classique, chaque bucket devient une série, auxquelles s'ajoutent _sum et _count : 17 séries par combinaison, soit jusqu'à 34 000 séries pour une seule métrique et une seule instance du service.
Ce dernier point est souvent oublié. Côté Prometheus, chaque instance de service (service.instance.id, traduit en label instance) multiplie encore le total, et chaque redéploiement remplace les instances par de nouvelles. Ce renouvellement permanent des séries, le churn, pèse sur le backend même quand le nombre de séries actives à un instant donné reste stable.
Avant de supprimer quoi que ce soit, il faut savoir où se concentre le volume. Sur Prometheus, la page TSDB Status de l'interface classe les noms de métriques et de labels par nombre de séries. Il est fréquent qu'une poignée de métriques, et quelques attributs sur ces métriques, expliquent l'essentiel du total.
Corriger à la source : conventions sémantiques et views
Le premier levier est de s'en tenir aux conventions sémantiques, qui ont été conçues avec la cardinalité en tête. Les conventions HTTP imposent que http.route soit un gabarit de route à faible cardinalité (/orders/{id}), jamais le chemin brut ; une méthode HTTP inconnue de l'instrumentation est ramenée à la valeur _OTHER ; et les attributs server.address et server.port, dérivés d'en-têtes HTTP, sont en opt-in, avec un avertissement explicite : un attaquant pourrait s'en servir pour atteindre les limites de cardinalité. L'URL complète existe bien dans les conventions, sous le nom url.full (l'ancien http.url est déprécié), mais comme attribut de span, pas de métrique.
Le second levier est la view du SDK. La spécification du SDK de métriques définit pour chaque view une liste blanche attribute_keys : les attributs absents de la liste sont ignorés, et l'agrégation se fait après ce filtrage, donc les valeurs restent justes. Les SDK devraient aussi accepter une liste d'exclusion. Nous préférons la liste blanche, parce qu'un attribut ajouté demain par une bibliothèque ou un collègue n'y entre pas par défaut.
La même spécification, au statut stable, prévoit une limite de cardinalité par métrique, de 2 000 combinaisons par défaut et par cycle de collecte. Au-delà, les mesures sont regroupées dans une série de débordement portant l'attribut otel.metric.overflow=true. Cette limite protège le backend, mais elle dégrade silencieusement la donnée : nous recommandons de surveiller l'apparition de cet attribut et de la traiter comme un défaut d'instrumentation. La spécification formule ces comportements en « SHOULD » : vérifiez leur prise en charge effective dans le SDK de votre langage.
Le Collector comme filet de sécurité
Faire transiter toute la télémétrie par un OpenTelemetry Collector reste une bonne pratique : c'est le seul endroit où appliquer une politique commune à tous les langages et à toutes les équipes, sans attendre leurs cycles de déploiement. Mais la manière de couper un attribut compte.
L'approche intuitive consiste à supprimer user.id avec l'action delete du processor attributes. Sa documentation est claire : ce processor ne réagrège pas les points. Retirer un attribut de points de métrique laisse plusieurs séries partager le même nom et les mêmes attributs : c'est le conflit d'identité que la documentation du Collector signale explicitement, et les valeurs qui arrivent au backend pour cette série n'ont plus de sens. Le même README indique d'ailleurs que le processor attributes est remplacé par transform.
Pour réduire réellement la cardinalité dans le Collector, nous utilisons la fonction aggregate_on_attributes du processor transform, avec une liste blanche. Les attributs absents de la liste sont supprimés, puis les points qui partagent les attributs restants sont additionnés (seule la somme est acceptée pour les histogrammes) :
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
processors:
memory_limiter:
check_interval: 1s
limit_percentage: 80
spike_limit_percentage: 20
transform/cardinalite:
error_mode: ignore
metric_statements:
- context: metric
statements:
- aggregate_on_attributes("sum", ["http.request.method", "http.route", "http.response.status_code", "error.type"]) where metric.name == "http.server.request.duration"
batch: {}
exporters:
prometheusremotewrite:
endpoint: https://prometheus.example.internal/api/v1/write
service:
pipelines:
metrics:
receivers: [otlp]
processors: [memory_limiter, transform/cardinalite, batch]
exporters: [prometheusremotewrite]
L'ordre des processors suit la recommandation de la documentation du Collector : memory_limiter en premier pour pouvoir refuser la charge, puis les filtres et les transformations, et batch en dernier. L'agrégation porte sur les points d'une même métrique au sein d'une même ressource : elle ne fusionne pas les séries de deux pods différents, ce qui est le comportement voulu. Elle reste une rustine. Le SDK a déjà payé le coût de ces séries en mémoire, et une règle centrale qui écrase un attribut finit toujours par surprendre l'équipe qui l'avait ajouté pour une bonne raison.
Deux autres composants reviennent souvent dans ces discussions, à tort ou à raison. Le processor filter supprime des métriques entières ; sur une métrique que personne ne consulte, c'est le gain le plus simple et le plus net. Le processor groupbyattrs, lui, n'est pas un outil de réduction : il déplace des attributs de point vers la ressource pour regrouper les données, sans changer le nombre de séries. Côté export, l'exporter prometheusremotewrite place par défaut les attributs de ressource dans une métrique target_info plutôt que sur chaque série. Recopier tous ces attributs en labels sur chaque série est possible, mais le gain de confort de requête se paie en volume d'index.
Le détail fin va dans les traces
Ces mécanismes ne servent qu'à faire respecter quelques règles simples, que nous posons dès le cadrage de l'instrumentation :
- Jamais d'identifiant utilisateur, de session ou de requête en attribut de métrique
- Des routes normalisées (
/orders/{id}) plutôt que des URL brutes - Aucun attribut de métrique dont les valeurs dépendent d'une entrée non maîtrisée, comme un en-tête
- Le détail fin reste dans les traces et les logs, pas dans les métriques
La dernière règle n'est pas une façon de déplacer le problème. Un span qui porte un user.id ne crée aucune série : son coût tient au volume stocké, pas au nombre de combinaisons. Ce volume se maîtrise par l'échantillonnage, et c'est là que le tail sampling devient intéressant.
Échantillonner après avoir vu la trace
Le processor tail_sampling décide après avoir reçu l'ensemble de la trace. Il peut ainsi conserver toutes les traces en erreur ou lentes, et seulement une fraction des traces nominales : dès qu'une politique retient la trace, elle est gardée. On conserve les traces utiles au diagnostic pour une fraction du volume.
receivers:
otlp:
protocols:
grpc: {endpoint: "0.0.0.0:4317"}
processors:
memory_limiter: {check_interval: 1s, limit_percentage: 80}
tail_sampling:
decision_wait: 10s
num_traces: 50000
policies:
- name: erreurs
type: status_code
status_code: {status_codes: [ERROR]}
- name: lentes
type: latency
latency: {threshold_ms: 1000}
- name: nominal
type: probabilistic
probabilistic: {sampling_percentage: 10}
batch: {}
exporters:
otlp/traces:
endpoint: traces.example.internal:4317
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, tail_sampling, batch]
exporters: [otlp/traces]
Ce confort a un prix architectural. Tous les spans d'une même trace doivent arriver sur la même instance du Collector, ce qui impose, dès qu'il y a plusieurs instances, une première couche équipée de l'exporter loadbalancing, qui répartit par traceID, devant la couche qui échantillonne. Le processor garde les spans en mémoire pendant decision_wait (30 secondes par défaut) dans un tampon circulaire limité par num_traces : une trace évincée avant la décision est perdue, et les spans arrivés après la décision peuvent recevoir un verdict différent du reste de leur trace. Raccourcir decision_wait économise de la mémoire, au risque de juger incomplètes les traces les plus longues, qui sont souvent celles que l'on voulait garder.
Dernier piège, plus sournois : toute métrique calculée à partir des spans après l'échantillonnage est biaisée, puisque les erreurs y sont conservées à 100 % et le trafic nominal à 10 %. Les métriques dérivées des traces, par exemple avec le connecteur spanmetrics, doivent être produites avant le tail sampling. Et les SLO doivent s'appuyer sur les métriques applicatives ou du load balancer, jamais sur des traces échantillonnées.
Tout cela suppose qu'une équipe porte la question. Nous recommandons de traiter un nouvel attribut de métrique comme un changement de schéma : il passe en revue de code avec une estimation de sa cardinalité, parce que c'est le seul moment où le retirer ne coûte rien.
Besoin d'aide sur ce sujet ?
Nos ingénieurs peuvent auditer votre contexte et vous proposer un plan d'action concret.