Lab 6 — Métriques métier

Un sac de paires clé → valeur attaché à chaque mesure. C’est lui qui permettra, à l’étape 4, de découper la métrique — « combien d’avis, et pour quelle note ? ».

La clé est typée, et se déclare une fois pour toutes :

private static final AttributeKey<Long>   RATING  = AttributeKey.longKey("app.review.rating");
private static final AttributeKey<String> PRODUCT = AttributeKey.stringKey("app.product.id");

Le type vit dans la clé, pas dans la valeur : le compilateur refuse Attributes.of(RATING, "cinq"). OpenTelemetry n’accepte que quatre types — String, Long, Double, Boolean — et leurs tableaux (stringArrayKey, longArrayKey…). Pas d’int, d’où le (long) dans le code du contrôleur.

Pourquoi static final ? D’abord parce qu’une clé d’attribut est une constante de l’application, au même titre que le nom de la métrique : déclarée en haut de la classe, elle s’écrit une fois et se relit partout. Recopiez la chaîne à la main dans deux appels, glissez un app.review.Rating dans l’un des deux, et vous obtenez deux séries distinctes — sans une erreur du compilateur ni le moindre message à l’exécution. Accessoirement, une AttributeKey porte un hash et un encodage UTF-8 précalculés, que le SDK réutilise à chaque mesure et à chaque export : la reconstruire à chaque avis créé, c’est refaire ce travail pour rien.

Plusieurs paires ? Attributes.of en accepte de une à six. Au-delà, ou quand une paire est conditionnelle, on passe par le builder :

Attributes.builder()
        .put(RATING, 5L)
        .put(PRODUCT, "OLJCESPC7Z")
        .build();

L’objet obtenu est immuable et trié : l’ordre d’écriture n’a aucune importance, {rating, product} et {product, rating} désignent la même série.

Et la taille ? Rien dans l’API ne vous empêche d’empiler les paires — mais le SDK, lui, plafonne à 2 000 combinaisons distinctes par instrument (DEFAULT_MAX_CARDINALITY, dans l’agent même que vous utilisez). Au-delà, les mesures ne sont pas jetées : le SDK remplace leurs attributs par otel.metric.overflow=true et les agrège toutes dans cette série unique.

La nuance compte pour lire un dashboard. Un sum(reviews_created_total) reste exact — rien n’est perdu. Mais un sum by (app_product_id) devient trompeur : tout ce qui a débordé se retrouve sous une seule étiquette au lieu d’être ventilé. Le seul avertissement arrive dans les logs du service (… has exceeded the maximum allowed cardinality (2000).), jamais dans Prometheus. L’étape 4 montre à quelle vitesse on s’approche de ce plafond.

Parce que l’API seule ne produit rien. GlobalOpenTelemetry.getMeter(...) renvoie par défaut une implémentation no-op : les appels add() et record() ne font littéralement rien, sans erreur ni surcoût. C’est la séparation fondamentale d’OpenTelemetry :

• l’API (opentelemetry-api) est ce que vous appelez dans votre code métier — légère, stable, sans dépendance ;
• le SDK est l’implémentation qui agrège, met en forme et exporte. Il est fourni ici par l’agent Java du Lab 2 : au démarrage de la JVM, l’agent installe son SDK dans GlobalOpenTelemetry, et vos appels deviennent d’un coup réels.

Concrètement, opentelemetry-api est la seule dépendance OpenTelemetry du pom.xml de review-service : l’agent seul suffit tant que le code n’importe rien de io.opentelemetry, et dès qu’il le fait, il faut ce JAR pour compiler. L’agent, lui, ne se déclare nulle part dans le pom.xml : il s’attache à la JVM au démarrage.

Conséquence pratique : une bibliothèque partagée peut s’instrumenter avec l’API sans imposer quoi que ce soit à ses utilisateurs. Et si vous retirez le -javaagent, l’application tourne toujours — sans métriques.

La chaîne de types est la même dans tous les langages : MeterProvider → Meter → instrument. Les trois maillons n’ont ni le même rôle ni le même nombre d’exemplaires :

Vous n’écrivez jamais le premier — GlobalOpenTelemetry.getMeter(...) est un raccourci pour getMeterProvider().get(...) — et c’est délibéré : votre code demande un guichet, il ne décide pas où partent les données. Vous l’avez pourtant déjà configuré au Lab 2 sans le nommer, puisque OTEL_EXPORTER_OTLP_ENDPOINT désigne l’exporter de ce provider, et OTEL_SERVICE_NAME sa Resource. C’est lui, enfin, qui explique la minute d’attente avant de voir une métrique apparaître : il collecte et exporte à intervalle fixe, 60 s par défaut, si bien qu’un add() n’envoie rien sur le réseau — il incrémente un total en mémoire, que le provider poussera au cycle suivant.

Le nom passé à getMeter() (fr.k8sschool.reviews) est le scope d’instrumentation : il identifie qui a produit la métrique, exactement comme l’otel.scope.name que vous verrez sur les spans au Lab 7.

Il n’y en a pas pour les métriques. Le module d’annotations d’OpenTelemetry n’en contient que trois — @WithSpan, @SpanAttribute, @AddingSpanAttributes (Lab 7) — et toutes produisent des spans. Ce n’est pas un oubli : un span commence et finit avec la méthode, une annotation suffit donc à le décrire. Un compteur métier, lui, s’incrémente à un endroit choisi du corps de la méthode, souvent sous condition — ici uniquement quand l’insertion a réussi — et avec une valeur d’attribut calculée (la note de l’avis). C’est pourquoi l’API métriques est impérative dans tous les langages. La seule voie déclarative existante est celle de Micrometer (@Timed, @Counted), qui n’accepte que des tags statiques.

Vous trouvez :

• reviews_created_total — votre compteur ;
• reviews_creation_duration_milliseconds_bucket, _sum et _count — votre histogramme.

Deux traductions ont eu lieu entre votre code et Prometheus :

• les points deviennent des _ (reviews.created → reviews_created) : le point n’est pas un caractère légal dans un nom de série Prometheus ;
• deux suffixes ont été ajoutés. _total marque un compteur monotone, c’est la convention Prometheus. Et _milliseconds vient de l’unité que vous avez déclarée dans le code (.setUnit("ms")) : la traduction OTLP → Prometheus développe l’unité et l’accole au nom. Déclarer une unité n’est donc pas décoratif — cela change le nom de la série.

Chemin parcouru : API OTel → SDK de l’agent → OTLP → collecteur → exporter otlphttp/prometheus → Prometheus. Retenez le principe : le nom que vous lisez dans Prometheus n’est jamais tout à fait celui que vous avez écrit dans le code. Cherchez par préfixe, pas par nom exact.

histogram_quantile(0.95, sum(rate(reviews_creation_duration_milliseconds_bucket[5m])) by (le))

sum by (app_review_rating) (reviews_created_total)

La seconde requête marche parce que le code a posé un attribut sur chaque point de mesure :

private static final AttributeKey<Long> RATING = AttributeKey.longKey("app.review.rating");
...
reviewsCreated.add(1, Attributes.of(RATING, (long) review.getRating()));

Un attribut de métrique devient un label Prometheus, et donc une série temporelle par valeur distincte. Une note vaut 1 à 5 : 5 séries, c’est gratuit. Le même code avec user.email à la place créerait une série par utilisateur — c’est l’explosion de cardinalité, la première cause de mort d’un Prometheus. Les identifiants vont dans les traces (où ils coûtent un attribut sur un span), jamais dans les métriques.

Et si on en mettait deux ? C’est la même méthode, avec deux paires :

private static final AttributeKey<String> PRODUCT = AttributeKey.stringKey("app.product.id");
...
Attributes.of(RATING,  (long) review.getRating(),
              PRODUCT, review.getProductId());

Vous obtiendriez alors des séries à deux labels, reviews_created_total{app_review_rating="5", app_product_id="OLJCESPC7Z"}. Mais leur nombre est le produit des valeurs, jamais leur somme — et le catalogue de la démo compte 10 produits :

Le SDK ne crée que les combinaisons réellement rencontrées, mais le plafond est bien celui-là. Sur un vrai catalogue de 50 000 références, cette même ligne donnerait 250 000 séries pour le compteur et 4 millions pour l’histogramme. Un attribut ne s’ajoute que si l’on sait par combien il multiplie — et un histogramme multiplie déjà par son nombre de seaux.

L’agent Java sait faire le pont — chaque meter Micrometer devient une métrique OTLP — mais ce bridge est désactivé par défaut, pour éviter les doublons avec les métriques que Spring Boot exporte parfois déjà de son côté. Il s’active par une variable d’environnement :

kubectl set env -n otel-demo deployment/review-service \
  OTEL_INSTRUMENTATION_MICROMETER_ENABLED=true
kubectl rollout status -n otel-demo deployment/review-service

Un meter qui reste invisible faute d’avoir activé son bridge est un classique du debug OTel : le code est juste, la configuration ne l’est pas.

reviews_creation_time_seconds_bucket, _sum, _count — le pendant Micrometer de votre histogramme. Notez l’unité : secondes, là où votre instrument OTel produisait des _milliseconds. Le même bloc de code, chronométré deux fois, à deux échelles : un Timer Micrometer publie toujours en secondes.

Mais surtout, regardez tout ce qui est arrivé avec. Relancez le comptage de l’étape 3 :

count(count by (__name__)({job="otel-demo/review-service"}))

Le nombre a plus que doublé — d’une cinquantaine de métriques à plus de cent trente — pour un seul Timer écrit à la main. Tout le reste, c’est le patrimoine Actuator que Spring Boot instrumente pour vous, et que le pont emporte avec : hikaricp_connections_* (le pool de connexions), jvm_gc_pause_seconds_*, tomcat_sessions_*, logback_events_total, spring_data_repository_invocations_seconds_*, application_ready_time_seconds…

C’est tout l’intérêt du pont : vous ne réécrivez pas votre instrumentation existante. Vous branchez l’agent, et le patrimoine Micrometer de l’application — le vôtre et celui d’Actuator — part en OTLP avec le reste.

Le revers se lit dans la même liste, et c’est la raison pour laquelle ce pont est fermé par défaut : une bonne partie de ces séries mesure ce que l’agent mesurait déjà, sous d’autres noms.

Deux mesures de la même chose, stockées deux fois. En production il faut trancher : garder le pont fermé et s’en tenir aux conventions OTel, ou l’ouvrir et écarter les doublons dans le collecteur (processor filter, cf. Lab 3).

Alors, API OpenTelemetry ou Micrometer ?

• API OpenTelemetry : la même dans tous les langages, aucun bridge à activer, et le seul chemin pour les traces et les logs. À privilégier pour du code neuf.
• Micrometer : ce que votre application Spring a déjà. À garder — et à faire sortir en OTLP par le pont plutôt qu’à réécrire.

Les deux cohabitent sans problème dans une même JVM, comme ici : ce service exporte les deux.

Spring Boot mesurait bien avant OpenTelemetry. Micrometer et Actuator comptent déjà les requêtes HTTP, le GC, les threads, le pool de connexions — et l’instrumentation OpenTelemetry mesure exactement les mêmes grandeurs, sous d’autres noms. Cumuler les deux produit donc mécaniquement des doublons. C’est pour cette raison que le pont est fermé par défaut, et c’est vrai de l’agent comme du starter.

Le même flag ouvre le pont dans les deux cas : OTEL_INSTRUMENTATION_MICROMETER_ENABLED=true.

Le starter est hors jeu pour ce lab, et pour une seule raison : il ne remplit pas GlobalOpenTelemetry, celui que le code de la partie 1 interroge. Vérifié sur le cluster — les deux instruments de l’étape 1 n’arrivent jamais, ils restent no-op faute de SDK derrière l’API.

Ni l’un ni l’autre reste possible : micrometer-registry-otlp pousse les meters au collecteur, micrometer-registry-prometheus expose /actuator/prometheus à scraper. Pas de doublons, puisqu’il n’y a qu’une instrumentation — mais ni traces, ni logs, ni corrélation : trois tuyaux séparés au lieu de la chaîne des Labs 4 et 5.

Reste à écarter les doublons, et deux façons simples suffisent :

• couper la mesure côté agent là où Micrometer fait déjà le travail. -Dotel.instrumentation.runtime-telemetry.enabled=false dans JAVA_TOOL_OPTIONS supprime les métriques JVM de l’agent et laisse celles d’Actuator (mesuré : jvm_gc_duration_seconds disparaît, jvm_gc_pause_seconds reste) ;
• les écarter au collecteur, avec le processor filter du Lab 3. Plus lourd — la donnée a déjà traversé le réseau — mais la règle s’écrit une fois pour toute la flotte.

⚠️ Ne coupez pas un module au hasard : il produit souvent des spans en plus des métriques. -Dotel.instrumentation.spring-webmvc.enabled=false ne supprime pas la métrique HTTP en double — il fait perdre la route, et POST /api/reviews devient POST /* dans les traces comme dans le label http_route.