OpenTelemetry pour messaging : tracing distribue

Une plateforme de messaging moderne au Maroc orchestre plusieurs services asynchrones : API de l'application metier, BSP WhatsApp, fallback SMS, webhooks de statut, base de donnees, file de messages. Quand un OTP prend anormalement 8 secondes pour arriver, ou que le taux de livraison chute, la question devient : ou exactement le temps a-t-il ete perdu ? OpenTelemetry apporte la reponse via le tracing distribue.

Le probleme sans tracing distribue

Sans instrumentation, on dispose de logs isoles par service. On sait qu'un envoi a echoue, mais reconstituer la chronologie complete (requete API entrante, appel BSP, retour Meta, webhook de delivery) demande de croiser manuellement plusieurs timestamps sur des heures d'incident. En prod, c'est ingerable.

Ce qu'apporte OpenTelemetry

OpenTelemetry (OTel) est le standard CNCF pour la collecte de trois signaux : traces, metrics, logs. Un trace represente le cycle de vie complet d'une requete a travers tous les services, sous forme d'un arbre de spans (unites de travail). Chaque span porte une duree, un statut, des attributs (par ex. numero WhatsApp cible, template utilise, code retour BSP).

Architecture typique pour du messaging

Les acteurs a instrumenter

• API Gateway qui recoit la demande d'envoi.
• Service messaging qui applique la logique metier.
• Broker (Kafka, Redis Streams, RabbitMQ) qui queue les envois.
• Worker BSP qui appelle l'API WhatsApp.
• Worker SMS Failback.
• Recepteur de webhooks qui traite les callbacks de statut.

La propagation du contexte

Le traceparent W3C se propage dans les headers HTTP et via les entetes des messages Kafka. Une convention utile : ajouter un message_id metier comme attribut sur tous les spans, ce qui permet de retrouver un OTP precis via une requete Jaeger ou Tempo.

Instrumentation en pratique

Auto-instrumentation

Les SDK OTel offrent une auto-instrumentation pour la plupart des frameworks : Express, Fastify, NestJS, Spring Boot, Django. Configuration minimale, gain immediat sur les spans HTTP entrants et sortants.

Instrumentation manuelle des points critiques

const span = tracer.startSpan('whatsapp.send', {
  attributes: {
    'messaging.system': 'whatsapp',
    'messaging.destination': hashedPhone,
    'messaging.template': templateName,
    'bsp.name': 'adrixis',
  },
});
try {
  const result = await bsp.sendMessage(...);
  span.setAttribute('waba.message_id', result.messageId);
} finally {
  span.end();
}

Correler les webhooks asynchrones

Un webhook de statut Meta arrive plusieurs secondes voire minutes apres l'envoi. Pour recoller le trace, stocker le trace_id initial dans la base indexee par message_id, puis creer un nouveau span enfant relie via span links au moment de la reception du webhook.

Metrics complementaires

Le tracing est cher a stocker exhaustivement. Compenser avec des metriques agregees :

• Histogramme de latence par etape (P50, P95, P99).
• Compteur d'echecs par code d'erreur BSP.
• Gauge du backlog dans le broker.
• Compteur SMS Failback declenche par raison (failed, timeout).

Stack recommande

• OpenTelemetry Collector comme point central de reception.
• Jaeger ou Grafana Tempo pour les traces.
• Prometheus pour les metriques.
• Loki pour les logs correles au trace_id.
• Grafana comme UI unifiee.

L'ensemble s'installe en quelques heures sur un cluster Kubernetes ou en managed (Grafana Cloud, Honeycomb, Datadog si budget disponible).

Sampling intelligent

Tracer 100 % des messages est couteux. Strategie efficace :

• Sampling tail-based qui garde 100 % des traces en erreur ou lentes (>3s).
• Echantillonnage bas (par ex. 10 %) pour les traces normales.
• Force sampling pour les comptes strategiques ou les incidents actifs.

Ce que le tracing permet de detecter

• Un endpoint BSP degrade dont la P95 double sans erreur visible.
• Un template mal configure qui ralentit la validation Meta.
• Une saturation de worker qui allonge la latence entre l'API et l'envoi effectif.
• Une correlation entre certains prefixes operateurs et des retards de webhook.

Conclusion

Pour une plateforme de messaging serieuse au Maroc, OpenTelemetry n'est plus un luxe reserve aux geants tech. C'est un standard operationnel qui divise par cinq le temps de diagnostic des incidents et fournit les preuves objectives quand un partenaire BSP conteste un SLA. L'investissement initial d'instrumentation se rentabilise typiquement des le premier incident majeur evite ou resolu rapidement.