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.

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.

⚠️ Attention à une confusion facile : le pom.xml contient bien opentelemetry-sdk, mais pour une tout autre raison — les classes de masquage PII du Lab 8 en ont besoin pour compiler, et elles ne servent qu’avec le profil starter. Or avoir le SDK dans le classpath ne l’active pas : un SDK ne produit rien tant que personne ne le construit et ne l’installe. Ici, aucune ligne de l’application ne le fait ; c’est l’agent qui s’en charge, de l’extérieur.

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.

L’agent n’est pas actif sur le pod en cours, et sans lui vos instruments restent no-op : aucune métrique n’arrivera, quoi que vous fassiez ensuite.

La cause la plus fréquente est d’avoir relancé deploy.sh depuis le Lab 5. Le script efface délibérément les variables posées à la main (JAVA_TOOL_OPTIONS, MASK_PII, OTEL_INSTRUMENTATION_MICROMETER_ENABLED) avant d’appliquer les manifestes, pour que ceux-ci restent la seule source de vérité — sans quoi un build starter se retrouverait avec l’agent par-dessus, soit deux SDK dans la même JVM.

Reprenez donc le Lab 5, étape 2, ou en trois commandes :

./scripts/deploy.sh
kubectl set env -n otel-demo deployment/review-service \
  JAVA_TOOL_OPTIONS="-javaagent:/otel/opentelemetry-javaagent.jar"
kubectl rollout status -n otel-demo deployment/review-service

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.

Le fichier de référence est 60-otel-metrics-values.yaml. Pour l’utiliser tel quel :

cp content/1_Labs/60-otel-metrics-values.yaml manifests/

Son contenu :

opentelemetry-collector:
  config:
    connectors:
      count:
        spans:
          app.spans.errors:
            description: "Number of spans with ERROR status"
            conditions:
              - status.code == STATUS_CODE_ERROR
    processors:
      deltatocumulative: {}
    service:
      pipelines:
        traces:
          exporters: [otlp/jaeger, debug, spanmetrics, count]
        metrics:
          receivers: [otlp, kafkametrics, spanmetrics, hostmetrics, postgresql, count]
          processors: [memory_limiter, resourcedetection, resource, deltatocumulative, batch]

Un connector est à la fois exporter d’un pipeline (traces) et receiver d’un autre (metrics) — les deux listes doivent le référencer.

Et pourquoi deltatocumulative ? Le connector count émet ses métriques en temporalité delta (chaque export = l’incrément depuis le précédent), or l’endpoint OTLP de Prometheus n’accepte que du cumulatif — sans ce processor, il répond HTTP 500 et le collecteur jette les points (Exporting failed. Dropping data. dans ses logs, exercice de debug classique).

Parce que le connector compte des spans, pas des requêtes. L’exception remonte toute la pile d’appels, et chaque span qu’elle traverse se termine en erreur :

POST /api/reviews          🔴 500   le span serveur
└── product-catalog.lookup 🔴       le span manuel du code (Lab 7)
    └── GET                🔴 500   l'appel HTTP vers le frontend

Allez voir la trace dans Jaeger (http://$PF_HOST:$UI_PORT/jaeger/ui/). Dans le panneau de recherche :

• Service : review-service
• Operation : POST /api/reviews
• Tags : error=true — c’est ce filtre qui compte, sans lui votre trace se noie parmi les requêtes réussies du générateur.

Cliquez sur Find Traces : la vôtre est en tête, marquée d’une pastille rouge. Dépliez-la, et vous constaterez que l’erreur n’est pas restée chez vous. Le frontend a été appelé, puis product-catalog : eux aussi ont leurs spans en erreur, et le total dépasse largement 3.

Relevé sur une de ces traces : 9 spans, dont 8 en erreur — 3 dans review-service, 4 dans le frontend, 1 dans product-catalog. sum(app_spans_errors_total) monte donc de 8 pour une seule requête, quand la série de votre service ne monte que de 3.

Le neuvième span, celui de la base de product-catalog, n’est pas en erreur : la requête SQL s’est exécutée normalement, elle n’a simplement rien trouvé. Un échec métier ne devient une erreur technique qu’à l’endroit où du code décide de lever une exception — ici, dans review-service.

C’est le point à retenir sur cette métrique : elle mesure la propagation d’une panne à travers le système, pas le nombre de requêtes ratées. Pour compter des requêtes, il faudrait ne retenir que les spans serveur — un seul par service et par requête. C’est l’objet de la dernière section du Lab 6 bonus, qui l’ajoute en quatre lignes de YAML.