Tracer une API

OpenAPI | gRPC

Après avoir déployé Extensible Service Proxy (ESP) ou Extensible Service Proxy V2 (ESPv2), ainsi que le code de backend de l'API, le proxy intercepte toutes les requêtes et effectue les vérifications nécessaires avant de les transférer au backend de l'API. Lorsque le backend répond, le proxy rassemble et consigne les données de télémétrie. Une partie des données de télémétrie capturées par le proxy correspond au traçage effectué à l'aide de Cloud Trace.

Cette page explique comment effectuer les actions suivantes :

• Afficher les traces dans la console Google Cloud
• Estimer le coût de Trace
• Configurez le proxy pour désactiver l'échantillonnage des traces.

Afficher les traces

Une trace suit avec un minutage précis une requête entrante adressée à votre API ainsi que les divers événements qui se produisent (tels que les appels RPC ou les sections de code mises en œuvre). Ces événements sont représentés sous forme de délais dans la trace.

Pour afficher les traces de votre projet, accédez à la page "Trace" dans la console Google Cloud :

Accéder à Stackdriver Trace

La page Explorateur de traces vous permet d'explorer une trace particulière et de voir les délais qu'ESP a créés à l'intérieur. Vous pouvez utiliser la fonction filtre pour n'afficher que les traces d'une seule API ou opération.

Les traces et les délais créés pour votre API varient selon qu'elle utilise ESPv2 ou ESP. Vous trouverez ci-dessous un récapitulatif des formats de trace pour chaque implémentation.

Pour en savoir plus sur la page Explorateur Trace, consultez Rechercher et explorer des traces

Délais créés par ESPv2

ESPv2 crée des traces au format suivant :

ESPv2 crée au moins deux délais par trace :

• Un délai ingress OPERATION_NAME pour l'ensemble de la requête et la réponse.
• Un délai router BACKEND egress pour la durée pendant laquelle ESPv2 attend que le backend traite la requête et y réponde. Ce délai inclut le saut de réseau entre ESPv2 et le backend.

En fonction de la configuration de l'API, ESPv2 peut créer des délais supplémentaires :

• Si l'API nécessite une authentification, ESPv2 met en cache pendant cinq minutes la clé publique dont il a besoin pour l'authentification. Si la clé publique ne figure pas dans le cache, ESPv2 la récupère et la met en cache, puis crée un délai JWT Remote PubKey Fetch.
• Si l'API nécessite une clé API, ESPv2 met en cache les informations nécessaires à la validation de la clé API. Si les informations ne figurent pas dans le cache, ESPv2 appelle Service Control et crée un délai Service Control remote call: Check.

En général, ESPv2 crée uniquement des délais pour les appels réseau qui bloquent la requête entrante. Les requêtes non bloquantes ne sont pas tracées. Tout traitement local crée des événements temporels au lieu de délais. Exemple :

• L'application des quotas nécessite des appels à distance, mais ces appels ne s'effectuent pas sur le chemin des requêtes API et ne produisent pas de délais dans la trace.
• Les clés API sont mises en cache par ESPv2 pendant une courte période. Toutes les requêtes qui utilisent le cache seront associées à un événement temporel dans la trace.

Délais créés par ESP

Avertissement : ESP ne fournit pas d'informations détaillées sur les délais. Il crée également des délais supplémentaires qui ne correspondent à rien. Veuillez migrer vers ESPv2 pour afficher des traces détaillées qui respectent les bonnes pratiques de traçage.

ESP crée des traces au format suivant :

ESP crée au minimum 4 délais par trace.

• Un délai pour la requête entière et la réponse.
• Un délai CheckServiceControl pour l'appel de la méthode services.check de Service Control afin d'obtenir la configuration de l'API.
• Un segment QuotaControl pour vérifier s'il existe ce quota configurés sur votre API.
• Un délai Backend qui suit le temps passé dans le code du backend de l'API.

En fonction de la configuration de l'API, ESP crée des délais supplémentaires :

• Si l'API nécessite une authentification, ESP crée un délai CheckAuth dans chaque trace. Pour authentifier une requête, ESP met en cache la clé publique dont il a besoin pour l'authentification pendant cinq minutes. Si la clé publique ne figure pas dans le cache, ESP la récupère et la met en cache, puis crée un délai HttpFetch.
• Si l'API nécessite une clé API, ESP crée un délai CheckServiceControlCache dans chaque trace. ESP met en cache les informations nécessaires à la validation de la clé API. Si les informations ne figurent pas dans le cache, ESP appelle Service Control et crée un délai Call ServiceControl server.
• Si vous avez défini un quota pour l'API, ESP crée un délai QuotaServiceControlCache dans chaque trace. ESP met en cache les informations nécessaires pour vérifier le quota. Si les informations ne figurent pas dans le cache, ESP appelle Service Control et crée un délai Call ServiceControl server.

Taux d'échantillonnage des traces

ESP échantillonne un petit nombre de requêtes adressées à l'API pour obtenir des données de trace. Pour contrôler le taux d'échantillonnage, ESP conserve les données relatives au nombre de requêtes et à leur minutage. Le nombre de requêtes par seconde adressées à l'API détermine le taux d'échantillonnage. Si aucune requête n'est envoyée en l'espace d'une seconde, ESP n'envoie pas de trace.

Si le nombre de requêtes en une seconde est :

• inférieur ou égal à 999, ESP envoie une trace ;
• entre 1 000 et 1 999, ESP envoie deux traces ;
• entre 2 000 et 2 999, ESP envoie trois traces ;
• Et ainsi de suite.

En résumé, vous pouvez estimer le taux d'échantillonnage avec la fonction ceiling : ceiling(requests per second/1000)

Estimer le coût de Trace

Pour estimer le coût de Trace, vous devez estimer le nombre de délais envoyés par ESP à Trace en un mois.

Pour estimer le nombre de délais par mois, procédez comme suit :

1. Estimez le nombre de requêtes par seconde adressées à l'API. Pour obtenir cette estimation, vous pouvez utiliser le graphique Requêtes sur la page Endpoints > Services ou Cloud Logging. Pour en savoir plus, consultez la section Surveiller une API.
2. Calculez le nombre de traces par seconde envoyées par ESP à Trace, avec la fonction suivante : ceiling(requests per second/1000)
3. Estimez le nombre de délais d'une trace. Pour obtenir cette estimation, vous pouvez utiliser les informations contenues dans Délais créés par ESP ou consultez la page Liste de traces pour voir les traces de votre API.
4. Estimez le nombre de secondes par mois pendant lesquelles l'API génère du trafic. Par exemple, certaines API reçoivent des requêtes uniquement à certaines heures de la journée et d'autres API reçoivent des requêtes sporadiquement.
5. Multipliez le nombre de secondes du mois par le nombre de délais.

Exemple :

1. Supposons que le nombre maximal de requêtes par seconde pour une API est de 5.
2. Le taux d'échantillonnage de trace est le suivant : CEILING (5/1000) = 1.
3. L'API n'a pas de quota configuré, et ne nécessite pas de clé API ni d'authentification. Par conséquent, le nombre de délais qu'ESP crée par trace est de 4.
4. Cette API reçoit les requêtes uniquement pendant les heures ouvrables, du lundi au vendredi. Le nombre de secondes pendant lesquelles l'API génère du trafic au cours d'un mois est d'environ : 3 600 x 8 x 20 = 576 000.
5. Le nombre de délais par mois est d'environ : 576 000 x 4 = 2 304 000.

Une fois que vous connaissez le nombre approximatif de délais par mois, consultez la page Tarifs de Trace pour obtenir des informations tarifaires détaillées.

Désactiver l'échantillonnage des traces

Si vous souhaitez qu'ESP cesse d'échantillonner les requêtes et d'envoyer des traces, vous pouvez définir une option de démarrage ESP et redémarrer ESP. Les traces qu'ESP envoie à Cloud Trace sont indépendantes des graphiques affichés sur la page Endpoints > Services. Les graphiques restent disponibles même si vous désactivez l'échantillonnage de trace.

La section suivante suppose que vous avez déjà déployé votre API et votre ESP, ou que vous connaissez le processus de déploiement. Pour en savoir plus, consultez la page Déployer le backend de l'API.

App Engine

Pour désactiver l'échantillonnage des traces ESP dans l'environnement flexible App Engine, procédez comme suit :

1. Modifiez le fichier app.yaml. Dans la section endpoints_api_service, ajoutez l'option trace_sampling et définissez sa valeur sur false. Exemple :

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     trace_sampling: false

   Si l'application est basée sur des microservices, vous devez inclure l'option trace_sampling: false dans chaque fichier app.yaml.

2. Si vous n'avez pas récemment mis à jour Google Cloud CLI, exécutez la commande suivante :

   gcloud components update

3. Enregistrez le ou les fichiers app.yaml.
4. Déployez le code de backend et ESP sur App Engine comme suit :

   gcloud app deploy

Pour réactiver l'échantillonnage des traces, procédez comme suit :

1. Supprimez l'option trace_sampling du fichier app.yaml.
2. Déployez le code de backend et ESP sur App Engine comme suit :

   gcloud app deploy

Instance

Pour désactiver l'échantillonnage de trace ESP sur Compute Engine avec Docker, procédez comme suit :

1. Connectez-vous à l'instance de VM :

   gcloud compute ssh [INSTANCE_NAME]

2. Dans les options ESP de la commande docker run, ajoutez l'option --disable_cloud_trace_auto_sampling :

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. Exécutez la commande docker run pour redémarrer ESP.

Pour réactiver l'échantillonnage de traces, procédez comme suit :

1. Supprimez l'option --disable_cloud_trace_auto_sampling.
2. Exécutez la commande docker run pour redémarrer ESP.

GKE

Pour désactiver l'échantillonnage de traces ESP sur GKE, procédez comme suit :

1. Ouvrez le fichier manifeste de déploiement (appelé deployment.yaml), puis ajoutez les éléments suivants à la section containers :

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. Démarrez le service Kubernetes à l'aide de la commande kubectl create :

   kubectl create -f deployment.yaml

Pour réactiver l'échantillonnage de traces, procédez comme suit :

1. Supprimez l'option --disable_cloud_trace_auto_sampling.
2. Démarrez le service Kubernetes :

   kubectl create -f deployment.yaml

Si vous exécutez ESP sur une instance de VM Compute Engine sans conteneur Docker, il n'existe aucune paire clé-valeur de métadonnées d'instance de VM équivalente pour l'option --disable_cloud_trace_auto_sampling. Si vous souhaitez désactiver l'échantillonnage de traces, vous devez exécuter ESP dans un conteneur.

Un client peut forcer le traçage d'une requête en ajoutant l'en-tête X-Cloud-Trace-Context à la requête, comme décrit dans la section Forcer le traçage d'une requête. Si une requête contient l'en-tête X-Cloud-Trace-Context, ESP envoie les données de trace à Trace même si vous avez désactivé l'échantillonnage de traces.

Propagation du contexte de trace

Pour le traçage distribué, un en-tête de requête peut contenir un contexte de trace qui spécifie un ID de trace. L'ID de trace est utilisé lorsque ESPv2 crée des délais de trace et les envoie à Cloud Trace. L'ID de trace permet d'effectuer une recherche sur l'ensemble des traces pour rassembler les délais d'une même requête. Si aucun contexte de trace n'est spécifié dans la requête et que le traçage est activé, un ID de trace aléatoire est généré et consigné dans tous les délais de trace.

Dans l'exemple suivant, Cloud Trace met côte à côte les délais créés par ESPv2 (1) et les délais créés par le backend (2) pour une même requête. Cela permet de déboguer les problèmes de latence sur l'ensemble du système :

Pour en savoir plus, consultez la page Concepts fondamentaux d'OpenTelemetry : propagation du contexte.

Remarque : Le traçage distribué nécessite que vos clients et/ou vos backends prennent en charge le traçage. Ceci n'est pas traité dans cette documentation. Nous vous recommandons d'utiliser OpenTelemetry.

En-têtes compatibles

ESPv2 accepte les en-têtes de propagation de contexte de trace suivants :

• traceparent: la norme W3C l'en-tête de propagation du contexte de trace. Compatible avec la plupart des frameworks de traçage modernes.
• x-cloud-trace-context : en-tête de propagation du contexte de trace GCP. En-tête spécifique à Google, compatible avec les anciens frameworks de traçage et les bibliothèques Google.
• grpc-trace-bin: en-tête de propagation du contexte de trace utilisé par les backends gRPC avec la bibliothèque OpenCensus de la bibliothèque de traçage.

Si vous créez une nouvelle application, nous vous recommandons d'utiliser la propagation du contexte de trace traceparent. Par défaut, ESPv2 extrait et propage cet en-tête. Consultez la section Options de démarrage du traçage dans ESPv2 pour obtenir plus de détails sur la modification du comportement par défaut.

Remarque : Contrairement à ESPv2, la propagation du contexte de trace dans ESP doit être activée manuellement via les options de démarrage. ESP n'est pas compatible avec l'en-tête traceparent.