Metrics in depth

1. Le modèle des métriques #

MeterProvider, meters, instruments.

De la mesure au point exporté #

Le code enregistre des mesures sur des instruments créés par un meter. Le SDK les agrège (somme, histogramme, dernière valeur) par combinaison d'attributs, puis un metric reader les exporte périodiquement (60 s par défaut, OTEL_METRIC_EXPORT_INTERVAL).

from opentelemetry import metrics
meter = metrics.get_meter("shop.checkout", "1.4.0")
commandes = meter.create_counter("shop.orders", unit="{order}", description="Commandes validées")
duree = meter.create_histogram("http.server.request.duration", unit="s")
commandes.add(1, {"shop.payment.method": "card"})
duree.record(0.183, {"http.request.method": "POST", "http.route": "/orders", "http.response.status_code": 201})

Les instruments #

2. Temporalité et histogrammes #

Deux notions qui surprennent.

Cumulative ou delta #

export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative   # ou delta, lowmemory

À savoir : Le processeur deltatocumulative du Collector convertit le delta en cumulatif avant un envoi vers Prometheus.

Histogrammes #

Erreur Courante : Les bornes par défaut sont en millisecondes « historiques » : pour une durée en secondes (unit="s"), définissez des bornes adaptées par une vue (0.005, 0.01, 0.025… 10) ou utilisez l'histogramme exponentiel.

3. Vues et cardinalité #

Contrôler ce qui est produit.

Les vues #

from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.view import View, ExplicitBucketHistogramAggregation, DropAggregation
provider = MeterProvider(metric_readers=[reader], views=[
    View(instrument_name="http.server.request.duration",
         aggregation=ExplicitBucketHistogramAggregation([0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5])),
    View(instrument_name="http.server.request.duration", attribute_keys={"http.request.method", "http.route", "http.response.status_code"}),
    View(instrument_name="db.client.connection.*", aggregation=DropAggregation()),   # supprimer des métriques inutiles
])

Cardinalité #

Chaque combinaison distincte d'attributs crée une série. 5 méthodes × 50 routes × 10 codes = 2 500 séries par instance. Un attribut user.id multiplie ce nombre par le nombre d'utilisateurs : le backend sature et la facture explose.

Bonne Pratique : Sur les métriques, n'utilisez que des attributs bornés (route, méthode, code, région). Les identifiants vont sur les spans et les logs.

4. Exemplars et Prometheus #

Relier une métrique à une trace.

Exemplars #

Un exemplar est un point de mesure particulier conservé avec son trace_id : sur un pic de latence p99, on clique sur l'exemplar et on ouvre la trace exacte d'une requête lente. Le filtre OTEL_METRICS_EXEMPLAR_FILTER=trace_based (défaut) n'enregistre que les mesures faites dans un span échantillonné.

Vers Prometheus #

# Prometheus 3 accepte l'OTLP nativement
prometheus --web.enable-otlp-receiver      # point d'entrée : /api/v1/otlp/v1/metrics
# ou dans le Collector : exportateur prometheusremotewrite, ou prometheus (scrape)