L'observabilité des API est la capacité de comprendre pourquoi votre API se comporte comme elle le fait en examinant la télémétrie qu'elle émet : métriques, journaux et traces. Cela va au-delà de la simple surveillance d'un ensemble fixe de tableaux de bord. Une API bien instrumentée vous permet de poser de nouvelles questions sur son état interne, y compris celles que vous n'aviez jamais anticipées, en utilisant uniquement les données qu'elle produit déjà.
Ce que l'observabilité des API signifie réellement
Le terme provient de la théorie du contrôle, où un système est observable si l'on peut en déduire son état interne à partir de ses sorties externes. Appliquée aux logiciels, une API est observable lorsque ses sorties (télémétrie) vous en disent suffisamment pour diagnostiquer tout comportement sans avoir à déployer de nouveau code pour ajouter une ligne de journal.
Cette dernière partie est importante. Avec l'observabilité, lorsqu'un client signale des requêtes de paiement lentes à 2 heures du matin pour des utilisateurs d'une région donnée sur une version d'API spécifique, vous devriez pouvoir répondre "pourquoi" à partir des données que vous collectez déjà. Vous instrumentez suffisamment pour enquêter sur des modes de défaillance que vous n'aviez pas prédits. C'est un objectif différent des vérifications de disponibilité, qui ne répondent qu'aux questions que vous saviez déjà poser.
Observabilité vs Surveillance
Les gens utilisent ces mots de manière interchangeable, mais ils décrivent des choses différentes.
La surveillance observe des signaux connus et alerte lorsqu'ils dépassent un seuil. Vous décidez à l'avance ce qu'il faut suivre (taux d'erreur, CPU, latence p99) et ce qui est considéré comme anormal. La surveillance répond à la question « est-ce que ce que j'attendais de tomber en panne est en train de tomber en panne ? »
L'observabilité est une propriété du système : la capacité de sa télémétrie à vous permettre de poser des questions arbitraires sur son état interne. Elle répond à la question « pourquoi cela se comporte-t-il de cette manière ? » même lorsque « cela » est quelque chose pour lequel vous n'avez jamais construit de tableau de bord.
En termes simples, la surveillance vous dit que quelque chose ne va pas. L'observabilité vous aide à en découvrir la raison. Vous avez besoin des deux. La surveillance vous donne l'alerte ; l'observabilité vous donne le chemin de l'alerte à la cause première. Si vous souhaitez un traitement plus approfondi de l'aspect alerte, notre guide sur la surveillance des API le couvre en détail.
Voici la distinction dans un tableau.
| Aspect | Surveillance | Observabilité |
|---|---|---|
| Question répondue | Un signal connu est-il hors de portée ? | Pourquoi le système se comporte-t-il ainsi ? |
| Défini quand | À l'avance (vérifications prédéfinies) | Au moment de l'investigation (requêtes ad hoc) |
| Idéal pour | Modes de défaillance connus, violations de SLO | Problèmes nouveaux, inattendus |
| Sortie | Alertes, tableaux de bord de statut | Télémétrie de haute cardinalité, interrogeable |
Les trois piliers : Métriques, Journaux, Traces
L'observabilité repose sur trois types de télémétrie, souvent appelés les trois piliers. OpenTelemetry, la norme neutre vis-à-vis des fournisseurs, les formalise comme des « signaux » de télémétrie. OpenTelemetry prend actuellement en charge les traces, les métriques, les journaux et le baggage, avec les événements et les profils en cours de développement. Les trois classiques correspondent à ses trois premiers signaux.
Métriques
Les métriques sont des mesures numériques agrégées sur le temps. Pour une API, les plus importantes sont le taux de requêtes, le taux d'erreur et la distribution de la latence. Signalez la latence sous forme de centiles (p95 et p99), pas seulement de moyennes. Une moyenne masque la "queue lente" que ressentent les vrais utilisateurs.
Les métriques sont peu coûteuses à stocker et rapides à interroger, ce qui les rend idéales pour les tableaux de bord et les alertes. Leur faiblesse est leur faible cardinalité : elles vous indiquent que la latence p99 a augmenté, mais pas quelles requêtes en sont la cause.
Journaux
Les journaux sont des enregistrements horodatés d'événements discrets. Les journaux structurés, émis au format JSON avec des champs cohérents, sont bien plus utiles que les lignes de texte libre car vous pouvez les filtrer et les agréger.
{
"timestamp": "2026-06-22T02:14:09Z",
"level": "error",
"method": "POST",
"path": "/v2/checkout",
"status": 503,
"duration_ms": 4812,
"trace_id": "8f3a1c9d2e7b4a16",
"user_region": "ap-southeast-1",
"api_version": "2026-05"
}
Notez le champ trace_id. Cet ID est ce qui relie une ligne de journal au flux de requête plus large, ce qui nous amène au troisième pilier.
Traces
Une trace distribuée suit une requête lorsqu'elle transite entre les services. Chaque saut devient un span, et les spans partagent un ID de trace afin que vous puissiez reconstituer le chemin complet et voir où le temps a été passé. Lorsqu'une requête passe par une passerelle, un service d'authentification et trois microservices, la trace indique quel saut a ajouté les 4 secondes.
Les traces sont ce qui rend le débogage des microservices gérable. Sans elles, vous ne faites que deviner quel service de la chaîne est lent.
Les trois piliers fonctionnent ensemble. Une alerte métrique signale le pic. Une trace pointe vers le service lent. Les journaux de ce service, filtrés par ID de trace, vous indiquent exactement ce qui s'est passé.
La méthode RED et les signaux d'or
Vous n'avez pas besoin de tout suivre. La méthode RED vous offre un point de départ ciblé pour tout service basé sur des requêtes. Tom Wilkie l'a introduite en 2015 chez Weaveworks, elle est dérivée des quatre signaux d'or de Google.
RED signifie :
- Taux (Rate) : requêtes par seconde traitées par votre API.
- Erreurs (Errors) : le nombre ou le taux de requêtes échouées, telles que les réponses 5xx et les réponses 4xx inattendues.
- Durée (Duration) : la distribution des latences de requête, signalée en p95 et p99.
Rate = requests/sec
Errors = % of 5xx (and unexpected 4xx) responses
Duration = latency distribution, report p95 and p99 (not just average)
RED est centré sur les requêtes, ce qui convient bien aux API, aux passerelles et aux maillages de services. Son homologue, USE (Utilisation, Saturation, Erreurs), cible les ressources d'infrastructure comme le CPU et le disque. Pour une API, commencez avec RED et ajoutez USE pour les hôtes sous-jacents.
SLI et SLO : Transformer les signaux en objectifs
Les données d'observabilité deviennent exploitables lorsque vous y associez des objectifs. Le livre SRE de Google définit deux termes ici.
Un indicateur de niveau de service (SLI) est une mesure quantitative d'un aspect de votre service. Les SLI courants sont la latence des requêtes, le taux d'erreur (la fraction de toutes les requêtes qui échouent) et le débit en requêtes par seconde. Ceux-ci s'alignent parfaitement avec RED.
Un objectif de niveau de service (SLO) est une valeur cible ou une plage pour un SLI. Par exemple : « 99,9 % des requêtes sur une fenêtre de 28 jours se terminent en moins de 300 ms. » Le SLO vous indique, à vous et à votre équipe, quand l'API est suffisamment saine et quand il faut consacrer du temps d'ingénierie à la fiabilité plutôt qu'aux fonctionnalités.
Les SLI et les SLO donnent un sens à vos métriques. Sans eux, un graphique de latence n'est qu'une ligne ondulée ; avec eux, c'est un contrat que vous pouvez mesurer.
Les outils : OpenTelemetry et les backends
Vous pouvez diviser les outils d'observabilité en deux couches : comment vous générez la télémétrie, et où vous l'envoyez.
Pour la génération, OpenTelemetry est la norme qu'il convient d'apprendre. C'est un projet de la Cloud Native Computing Foundation (CNCF), formé par la fusion d'OpenTracing et d'OpenCensus. Il est indépendant des fournisseurs et des outils, il fonctionne donc avec une large gamme de backends. Son principe fondamental est que vous êtes propriétaire des données que vous générez, sans verrouillage fournisseur. Il fournit des API, des SDK de langage, des conventions sémantiques, le protocole filaire OTLP, l l'auto-instrumentation et l'OpenTelemetry Collector.
Pour le stockage et l'analyse, vous avez des options. Prometheus associé à Grafana est une pile open source courante pour les métriques et les tableaux de bord. Des plateformes commerciales comme Datadog et Honeycomb ingèrent les traces, les métriques et les journaux et offrent des requêtes à haute cardinalité. Si vous utilisez Datadog, notre présentation de l'API Datadog montre comment envoyer et récupérer des données par programmation.
L'intérêt d'OpenTelemetry est que vous instrumentez une fois, puis changez de backend sans ré-instrumenter. Cette portabilité est la principale raison de l'adopter tôt.
Où les tests et les vérifications synthétiques s'intègrent
L'observabilité n'est pas qu'une préoccupation de production. Certains des signaux les plus utiles proviennent des tests que vous exécutez intentionnellement, avant et après le déploiement.
Déplacement à gauche : tests de contrat et exécutions CI
Avant le déploiement du code, les tests de contrat vérifient que votre API correspond toujours à sa spécification. L'exécution de ceux-ci en CI détecte les changements potentiellement perturbateurs avant qu'ils n'atteignent les utilisateurs. Chaque exécution de test CI est un signal : un succès ou un échec lié à un commit, un environnement et un horodatage. Cet historique est une donnée d'observabilité sur la qualité de votre version.
L'interface de ligne de commande Apidog exécute vos scénarios de test dans un pipeline. Elle est basée sur Node.js et nécessite Node v16 ou supérieur.
npm install -g apidog-cli
# verify the install
node -v && apidog -v
Exécutez un scénario de test sur un environnement. L'indicateur d'environnement est requis, et vous transmettez votre jeton explicitement.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli
Ici, -t est l'ID du scénario de test, -e est l'ID de l'environnement, et -r définit les formats de rapport (cli, html, json, junit). Le rapporteur par défaut est cli. Pour exécuter le scénario à partir d'un fichier CSV ou JSON, ajoutez -d ./data.csv (l'option -d, ou --iteration-data, prend un chemin de fichier). Vous pouvez également envoyer un aperçu du rapport vers le cloud Apidog.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report
Pour un pipeline complet que vous pouvez copier et adapter, consultez notre guide Apidog CLI pour CI/CD, ou la référence complète de la CLI pour chaque option.
Surveillance synthétique en production
La surveillance synthétique exécute des requêtes scriptées contre votre API en direct selon un calendrier, de l'extérieur, de la même manière qu'un utilisateur le ferait. Elle détecte les problèmes avant le trafic réel et vous fournit un flux constant de points de données de latence et de disponibilité. Une vérification de santé d'API de base est la forme la plus simple. La surveillance synthétique complète l'étend aux flux en plusieurs étapes comme la connexion puis le paiement.
Ces vérifications sont des signaux d'observabilité à part entière. Une exécution synthétique échouée à 02:00 avec une durée de 4 secondes est exactement le type d'événement que vous souhaitez alimenter vos traces et vos journaux. Pour un aperçu des outils dédiés, consultez notre récapitulatif des outils de test synthétiques, et pour les plateformes de surveillance de production, notre liste d'outils de surveillance d'API.
Générer des signaux réels avec les tâches planifiées d'Apidog
Apidog peut produire des signaux synthétiques récurrents via les Tâches Planifiées. Cette fonctionnalité exécute automatiquement des scénarios de test configurés à des heures définies, capture les résultats et prend en charge les tests de régression planifiés. Vous la trouverez sous le module Tests, dans Tâches Planifiées.
Quelques points à savoir avant de vous y fier. Les Tâches Planifiées sont actuellement en version Bêta, il faut donc les considérer comme une fonctionnalité en évolution plutôt que stable à long terme. Elle nécessite également un Runner auto-hébergé configuré ; les options « Exécuter sur » listent un Runner auto-hébergé aujourd'hui, avec Apidog Cloud répertorié comme bientôt disponible. Il n'y a donc pas encore de vérification planifiée entièrement hébergée dans le cloud.
Lorsque vous en configurez une, vous choisissez :
- Scénarios de test : un ou plusieurs scénarios à exécuter.
- Mode d'exécution : un cycle de temps, par exemple tous les dimanches à 23h ou toutes les 6 heures.
- Notification : alertes après chaque exécution, ou seulement en cas d'échec.
Le nombre d'exécutions dépend de votre plan d'abonnement. Pour une implémentation pratique, consultez notre guide des Tâches Planifiées d'Apidog.
L'intérêt ici est de boucler la boucle. Vous concevez et testez votre API au même endroit, puis exécutez ces mêmes scénarios à un rythme régulier afin qu'ils continuent à générer des signaux de succès/échec et de latence sur lesquels vous pouvez agir. Essayez Apidog gratuitement, sans carte de crédit, et transformez vos scénarios de test existants en signaux récurrents.
Un chemin pratique vers une API observable
Si vous partez de zéro, travaillez dans cet ordre :
- Émettez des journaux structurés avec un schéma cohérent et un ID de trace pour chaque requête.
- Instrumentez avec OpenTelemetry afin que les traces, les métriques et les journaux partagent le contexte et restent portables entre les backends.
- Suivez les métriques RED (taux, erreurs, durée avec p95 et p99) et affichez-les sur un tableau de bord.
- Définissez des SLI et des SLO afin que vos métriques aient des objectifs, et pas seulement des tendances.
- Ajoutez des tests de contrat en CI pour détecter les changements potentiellement perturbateurs avant la publication.
- Exécutez des vérifications synthétiques selon un calendrier en production, par exemple avec les Tâches Planifiées d'Apidog.
Vous n'êtes pas obligé de faire les six étapes en même temps. Même la première étape, les journaux structurés avec des ID de trace, vous fait progresser considérablement par rapport aux journaux textuels bruts.
Foire Aux Questions
Qu'est-ce que l'observabilité des API ?
L'observabilité des API est la capacité de comprendre l'état interne d'une API à partir de la télémétrie qu'elle émet, c'est-à-dire les métriques, les journaux et les traces. Une API observable vous permet d'enquêter sur les raisons de son comportement, y compris les problèmes que vous n'aviez pas anticipés, sans ajouter de nouvelle instrumentation au préalable.
Observabilité API vs surveillance : quelle est la différence ?
La surveillance observe des signaux prédéfinis et alerte lorsqu'ils dépassent un seuil, répondant à la question « est-ce que ce que j'attendais de tomber en panne est en train de tomber en panne ? » L'observabilité est une propriété du système qui vous permet de poser de nouvelles questions arbitraires sur son comportement, répondant à « pourquoi cela se produit-il ? » La surveillance vous dit que quelque chose ne va pas ; l'observabilité vous aide à en trouver la cause. Vous avez besoin des deux.
Quels sont les trois piliers de l'observabilité ?
Les trois piliers sont les métriques, les journaux et les traces. Les métriques sont des nombres agrégés comme le taux de requêtes et les centiles de latence. Les journaux sont des enregistrements horodatés d'événements discrets, idéalement structurés en JSON. Les traces suivent une requête à travers les services afin que vous puissiez voir où le temps a été passé. OpenTelemetry les formalise comme des signaux de télémétrie.
Comment rendre une API observable ?
Commencez par émettre des journaux structurés avec un ID de trace pour chaque requête. Instrumentez votre code avec OpenTelemetry afin que les métriques, les journaux et les traces partagent le contexte. Suivez les métriques RED, définissez les SLI et les SLO comme objectifs, ajoutez des tests de contrat en CI, et exécutez des vérifications synthétiques planifiées en production. Chaque étape ajoute un signal interrogeable.
OpenTelemetry est-il requis pour l'observabilité ?
Non. L'observabilité est une propriété que vous pouvez atteindre avec n'importe quel outil de télémétrie, et de nombreuses équipes utilisaient des agents propriétaires bien avant l'existence d'OpenTelemetry. Cela dit, OpenTelemetry est la norme CNCF neutre vis-à-vis des fournisseurs, donc l'adopter vous permet d'instrumenter une fois et de changer de backend comme Prometheus, Datadog ou Honeycomb sans ré-instrumenter. C'est un choix par défaut solide, pas une exigence.