Une API de gestion de commandes commence avec trois chronomètres et quelques logs. Deux ans plus tard, chaque service ouvre son span, ajoute dix attributs et journalise le même identifiant. Une refonte de télémétrie oblige alors à modifier des règles de prix, tandis qu’un incident reste inexplicable parce que le résultat métier n’a jamais été enregistré.
Le vrai enjeu est de concentrer l’instrumentation aux frontières et de laisser au domaine une seule responsabilité : nommer les résultats utiles. Les adaptateurs HTTP, bus, clients et accès aux données mesurent les mécanismes. Les cas d’usage publient un résultat stable sans connaître l’exporteur, le collecteur ou le tableau qui le consommera.
Contre-intuitivement, davantage de spans dans le code ne produit pas nécessairement une meilleure explication. Des attributs variables font exploser les séries, des messages libres cassent les requêtes et un identifiant personnel peut créer un risque inutile. Une instrumentation légère est d’abord une architecture et une gouvernance.
Pour une API métier développée sur mesure, cette méthode relie résultat, contexte, preuve et coût. Elle s’appuie sur OpenTelemetry et W3C Trace Context sans présenter ces standards comme une garantie automatique de fiabilité.
Séparer le contrat d’observation du code métier
Observer une décision, pas une librairie
Le contrat part d’une question d’exploitation : combien de commandes sont acceptées, refusées, inconnues ou terminées après leur échéance ? Il définit événement, horodatage, résultat, version et attributs autorisés. Une classe de domaine ne choisit ni format de log ni nom de compteur.
Le cas d’usage retourne une valeur typée ou publie un événement métier. Un adaptateur traduit ce résultat en métrique, événement de trace et log structuré. Changer de backend d’observabilité ne doit pas modifier la règle qui calcule l’éligibilité d’une commande.
Garder le domaine testable sans SDK
Les tests unitaires créent une commande et vérifient sa décision sans initialiser de collecteur. Un port facultatif peut recevoir un événement si l’architecture l’exige, mais son vocabulaire reste celui du produit. L’implémentation de télémétrie demeure en infrastructure et peut devenir inactive sans changer le résultat.
Instrumenter les frontières une seule fois
Un middleware HTTP mesure méthode normalisée, route, statut, taille et durée. Il ne prend pas l’URL brute comme attribut, car les identifiants dans le chemin multiplient les valeurs. Le framework fournit souvent cette auto-instrumentation ; l’équipe vérifie ses conventions avant d’ajouter une couche concurrente.
Le bus de messages, le client HTTP, le pool SQL et le worker possèdent le même type de décoration. Ces composants voient attente, tentative, timeout et résultat technique. L’instrumentation transversale couvre alors tous les cas d’usage sans copier un bloc dans chaque contrôleur.
Éviter la double mesure
Si l’agent et le middleware créent tous deux un span serveur, alors la trace ment sur la profondeur et double les volumes. Une carte d’instrumentation nomme le propriétaire de chaque frontière. Le test d’intégration attend un span serveur, pas deux, et vérifie les attributs indispensables.
Émettre des résultats métier stables
La frontière HTTP sait qu’une réponse vaut 409, mais pas si le conflit protège un stock déjà réservé ou révèle une course inattendue. Le cas d’usage produit un code stable comme stock_insuffisant, commande_dupliquee ou etat_inconnu. L’adaptateur l’ajoute aux signaux autorisés.
Ce code ne reprend pas le message traduit présenté à l’utilisateur. Il constitue une dimension gouvernée dont la liste reste bornée. Les nouveaux résultats passent une revue de schéma ; renommer un code requiert une période de compatibilité pour ne pas casser alertes et analyses.
Mesurer le résultat final
Une requête acceptée pour traitement asynchrone n’est pas une commande terminée. L’événement d’acceptation et l’événement final sont distincts, reliés par un identifiant opaque. Le SLI métier choisit celui qui correspond à la promesse et garde les états inconnus visibles.
Répartir métriques, traces et logs
Une métrique répond à une tendance agrégée : taux de résultats, débit, latence ou âge de file. Une trace raconte le chemin d’un échantillon entre composants. Un log structuré conserve un événement ou un changement d’état utile à l’enquête. Les trois rôles évitent de transformer chaque signal en copie exhaustive.
Le tableau détecte une hausse de refus ; un exemplaire de trace localise l’attente ; le log de décision explique la version de règle. Cette navigation exige identifiants et horloges cohérents. Elle ne suppose pas que toutes les requêtes disposent d’une trace conservée.
Commencer par la question
Avant d’ajouter un champ, l’équipe écrit la requête ou la décision qu’il servira. Si personne ne sait comment l’utiliser, alors il reste hors du schéma pilote. Cette discipline réduit bruit, coût et tentation de collecter une donnée personnelle au cas où.
Choisir des noms et attributs gouvernés
Les conventions sémantiques OpenTelemetry fournissent des noms partagés pour HTTP, bases et messagerie. L’équipe les adopte lorsque leur statut et leur sens correspondent à sa version du SDK. Les attributs métier restent dans un espace nommé et documenté.
Service, environnement, version et instance sont des ressources, pas des champs répétés arbitrairement. Route, opération et code de résultat doivent avoir une cardinalité bornée. Identifiant de commande, email ou texte d’erreur ne devient pas un label de métrique.
Versionner le dictionnaire
Une fiche indique nom, type, valeurs, source, sens et niveau de sensibilité. Le linter ou un test vérifie les constantes. Une dépréciation conserve l’ancien champ pendant une fenêtre définie, puis mesure encore ses consommateurs avant suppression.
Propager le contexte sans le faire fuiter
Le standard W3C Trace Context définit notamment traceparent et tracestate pour relier des appels. La bibliothèque extrait et injecte ces en-têtes aux frontières autorisées. Le code métier ne concatène pas lui-même un identifiant de trace.
Une frontière de confiance peut filtrer ou recréer le contexte. Un en-tête reçu n’est pas une preuve d’identité et ne doit jamais décider un droit. Les réponses publiques ne renvoient pas automatiquement des informations internes ; l’équipe sépare identifiant de support et contexte de trace.
Relier asynchrone et traitement différé
Le contexte utile traverse les métadonnées du message selon le standard supporté. Pour un traitement très différé, un lien de span peut mieux représenter la causalité qu’un unique span enfant gardé artificiellement ouvert. La date métier et l’identifiant d’opération complètent la chronologie.
Couvrir clients, base et traitements asynchrones
Le client externe mesure nom logique de dépendance, opération, délai, statut normalisé et tentative. Il masque secrets et paramètres. Un retry apparaît comme plusieurs tentatives sous une opération afin que l’exploitant distingue latence partenaire et politique locale.
La base conserve système, opération et durée. Le texte SQL complet ne doit pas être collecté sans revue : il peut contenir valeurs et créer une cardinalité élevée. Un hash ou un nom de requête stable aide à relier plan et régression dans un accès restreint.
Mesurer la file au-delà du consommateur
Le worker observe temps d’attente, durée de traitement, tentative, issue et âge du message. Un message envoyé en quarantaine produit un résultat explicite. La profondeur de file seule ne prouve pas une dégradation ; l’âge et le débit de sortie donnent la marge.
Qualifier erreurs, refus et états inconnus
Une exception non gérée est une erreur technique. Un refus métier attendu n’est pas forcément une erreur du service, mais reste un résultat à compter. Un timeout après une écriture distante crée un état inconnu tant qu’un rapprochement n’a pas confirmé l’effet.
Le span peut porter un statut d’erreur lorsque l’opération observée échoue, tandis que le code métier précise l’issue. Un message d’exception est nettoyé et l’objet complet n’est pas sérialisé par défaut. La stack est réservée aux canaux et droits adaptés.
Ne pas rendre le succès mensonger
Retourner HTTP 200 avec un champ success=false empêche l’auto-instrumentation de comprendre seule. Le contrat HTTP devrait être corrigé lorsque possible. En attendant, l’événement métier et une métrique dédiée préservent la réalité sans falsifier le statut générique.
Échantillonner sans perdre les cas critiques
Conserver toutes les traces peut être inutile ou coûteux. Un taux local est calibré sur volume, budget et questions. Le head sampling décide tôt mais ignore le résultat futur ; le tail sampling peut retenir erreur ou lenteur après observation, au prix d’un collecteur plus complexe et dimensionné.
Les métriques de résultats ne doivent pas dépendre des traces échantillonnées. Les événements critiques peuvent disposer d’un canal durable distinct. Un échantillonnage à 5 % est un exemple de pilote, pas une recommandation générale : sur faible trafic il peut ne produire aucun cas exploitable.
Tester le biais
La recette envoie succès, refus, erreur, lenteur et volume de pointe. Elle compare événements produits, exportés et requêtables. Si les traces lentes disparaissent, alors la politique ou la capacité du collecteur doit être corrigée avant de promettre le diagnostic.
Borner coût, cardinalité et données sensibles
Le budget d’observabilité suit octets exportés, séries actives, débit du collecteur, latence ajoutée et erreurs d’export. Un seuil local peut alerter lorsque le coût par requête double après une release ; il doit être comparé au volume et au changement de schéma.
L’export se fait hors du chemin critique autant que le SDK le permet, avec files bornées. Quand le backend est indisponible, l’API doit continuer selon sa criticité ; elle compte les signaux perdus et alerte. Une file infinie déplacerait la panne vers la mémoire du service.
Appliquer la minimisation
Les attributs passent une revue de sensibilité et de rétention. Les identifiants métier sont hachés uniquement si le modèle de menace rend ce choix utile ; un hash prévisible n’anonymise pas toujours. Le besoin de support se satisfait souvent avec un identifiant de corrélation opaque et une table protégée.
Cas concret : une commande déclarée perdue
Cas concret hypothétique. Un client interne reçoit un timeout après validation. Le ticket dit commande perdue, tandis que l’ERP l’a créée. L’API a retenté et obtenu un conflit. Les anciens logs contiennent trois messages libres sans lien entre tentative et résultat.
L’équipe instrumente le middleware, le client ERP et le bus. Le cas d’usage émet commande_etat_inconnu, puis le rapprochement publie commande_confirmee. Un identifiant d’opération relie les deux, tandis que chaque tentative conserve son propre span.
Le tableau montre dix états inconnus sur la fenêtre ; huit sont confirmés avant cinq minutes et deux nécessitent une action. Une trace retenue confirme une latence ERP contributive. Elle ne prouve pas à elle seule la cause des dix cas. La correction ajoute une clé d’idempotence et une reprise contrôlée, puis mesure le délai de rapprochement.
Pour qui cette architecture est adaptée
Elle convient aux équipes qui exploitent une API avec plusieurs contrôleurs, workers ou dépendances et qui perdent du temps à corréler. Un service simple peut commencer par middleware, métriques de résultats et logs structurés. Il n’a pas besoin d’un pipeline de tracing distribué complet.
Produit nomme les issues, développement tient les frontières, exploitation définit les questions, sécurité cadre les données et la plateforme maintient collecte et conventions. Une petite équipe peut cumuler les rôles, mais les décisions restent explicites pour éviter le schéma sans propriétaire.
Éviter les erreurs fréquentes d’instrumentation
Créer des spans dans chaque méthode
Cette granularité reflète l’organisation du code plutôt que le parcours. Elle augmente volume et couplage. Les spans manuels se réservent aux étapes dont la durée ou la causalité éclaire une décision et que l’auto-instrumentation ne voit pas.
Mettre les identifiants en labels
Une série par commande rend les métriques coûteuses et parfois inutilisables. Les valeurs fortement variables vont dans des traces ou événements à accès maîtrisé. Les métriques gardent des dimensions bornées comme route, résultat et cohorte validée.
Rendre l’exporteur bloquant
Une panne d’observabilité ne doit pas immobiliser silencieusement l’API. Les files, timeouts, pertes et modes d’échec du SDK sont testés. En revanche, une obligation d’audit peut imposer un canal durable différent : elle doit être conçue comme une exigence métier, pas confondue avec le debug.
Arbitrer auto-instrumentation et code explicite
Si une frontière standard est supportée, alors l’auto-instrumentation ou un décorateur partagé réduit les duplications. En revanche, un résultat métier ne peut pas être deviné depuis le statut HTTP. Dans ce cas, un événement explicite et stable complète le mécanisme.
Un span manuel se justifie lorsqu’une étape a une latence propre, traverse une abstraction invisible ou sépare deux hypothèses opérationnelles. Il ne doit pas reproduire une fonction uniquement pour obtenir un joli arbre. Plutôt que compter les spans, la revue vérifie les questions résolues.
Pour une API à faible volume et sans appel distant, métriques de résultat et logs structurés peuvent suffire. Si plusieurs composants se partagent un incident et que la chronologie reste coûteuse, alors la propagation et quelques traces prennent de la valeur. Le choix dépend du temps perdu, du volume, du budget et des compétences d’exploitation.
Une obligation d’audit n’impose pas de conserver toutes les traces. Elle exige une preuve durable conçue pour ce besoin, avec intégrité, droits et rétention. En revanche, le diagnostic temporaire peut rester échantillonné. Dans ce cas, les deux canaux doivent être nommés séparément afin qu’une perte de télémétrie ne soit pas confondue avec une perte de preuve.
- Si le résultat manque, alors qualifier d’abord l’issue et la question opérationnelle.
- En revanche, si le transport manque, choisir la frontière commune qui porte déjà le contexte.
- Dans ce cas, ajouter un événement métier seulement lorsque le mécanisme ne suffit pas.
- Plutôt que généraliser immédiatement, mesurer coût, pertes et capacité de diagnostic avant extension.
Fermer le contrat d’implémentation
Les entrées sont requête, message, contexte autorisé et version. Les sorties sont résultat, durée et preuve corrélable. Les dépendances sont SDK, collecteur et backend. Les responsabilités nomment le propriétaire des conventions, de l’export et de chaque événement métier.
Le monitoring suit pertes, file d’export, latence et schémas inconnus. La journalisation décrit changements de résultat. Le repli désactive un instrument ou réduit l’échantillonnage sans redéployer le domaine. Le guide de reprise couvre collecteur saturé et backend indisponible.
Tester le signal comme une interface
Un test d’intégration exécute une requête, un refus, une erreur et un message asynchrone avec un exporteur en mémoire. Il vérifie noms, types, absence de secret, unicité des spans de frontière et propagation. Il n’impose pas l’ordre de tous les attributs ni un détail privé du SDK.
Un test de défaillance coupe l’exporteur, remplit la file bornée et confirme que l’API suit sa politique. La performance compare une baseline reproductible ; un budget local de surcharge est défini selon latence, volume et marge, sans généraliser un chiffre universel.
Plan d’action sur six semaines
Semaines 1 et 2 : cartographier et choisir
L’équipe choisit deux parcours incidentés et liste frontières, questions, résultats et données sensibles. Elle inventorie l’instrumentation automatique existante pour éliminer les doublons. Cinq à huit attributs stables forment un dictionnaire pilote avec propriétaires, types et exemples.
Elle rejoue des tickets récents avec les signaux actuels, chronomètre la corrélation et nomme les trous. Chaque ajout doit répondre à un trou observé. Les routes brutes, identifiants personnels et messages libres sont exclus des dimensions avant toute collecte.
Semaines 3 et 4 : implémenter aux frontières
Les décorateurs HTTP, client et message sont activés dans un environnement de recette. Les cas d’usage publient leurs quelques résultats typés. Le pipeline borne files, délais et échantillonnage. Une revue sécurité valide propagation, accès et rétention.
La recette injecte timeout, retry, conflit, refus et état inconnu. Elle compare métriques, traces et logs au résultat de référence. Une autre personne part d’un tableau, trouve un exemplaire et explique la chronologie sans accès oral aux auteurs.
Semaines 5 et 6 : éprouver et étendre
Le pilote reçoit une part de trafic et observe coût, latence ajoutée, séries, pertes et cas diagnostiqués. Un drapeau permet de réduire un instrument. Toute divergence de schéma ou donnée interdite bloque l’extension, même si le tableau paraît utile.
L’équipe rejoue un incident et compare temps d’explication, pas seulement temps d’alerte. Elle corrige conventions et guide de reprise, puis étend frontière par frontière. La sortie exige un propriétaire, une requête utile et un test ; les signaux décoratifs sont supprimés.
Relier instrumentation, workflow et tracing
La documentation officielle OpenTelemetry PHP sur l’instrumentation décrit API et SDK ; les versions réellement installées restent la référence d’intégration. Elle ne remplace pas le contrat de résultat métier.
L’observabilité d’un workflow métier aide à choisir les changements d’état, tandis que les critères d’adoption du tracing distribué évitent de suréquiper un service simple.
- Concentrer la mesure mécanique sur les frontières partagées.
- Émettre seulement les résultats métier nécessaires aux décisions.
- Tester propagation, pertes, coût et minimisation avant extension.
Conclusion : observer sans contaminer le domaine
Une API bien instrumentée ne porte pas un appel de télémétrie dans chaque règle. Ses frontières mesurent le transport et ses cas d’usage nomment quelques résultats durables.
Métriques, traces et logs ont des fonctions complémentaires. Leur valeur vient des conventions, de la corrélation et de la possibilité de retrouver une preuve, pas du volume collecté.
L’équipe avance par questions et incidents rejoués. Elle borne cardinalité, sensibilité et surcharge, puis retire ce qui n’éclaire aucune décision.
Dawap peut concevoir cette architecture dans une mission de développement web métier, avec un accompagnement expert de l’instrumentation pilote jusqu’à son exploitation et sa reprise.
