Tracer une API

Une fois que vous avez déployé Extensible Service Proxy (ESP) et le code de backend de l'API, ESP 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, ESP rassemble et consigne les données de télémétrie. Une partie des données de télémétrie capturées par ESP correspond au traçage effectué à l'aide de Cloud Trace.

Cette page explique comment effectuer les actions suivantes :

  • Afficher les traces dans Google Cloud Console
  • Estimer le coût de Trace
  • Configurer ESP pour désactiver l'échantillonnage de trace

Afficher les traces de votre API

Pour afficher les traces de votre API, procédez comme suit :

  1. Accédez à la page Endpoints > Services de votre projet :

    Accédez à la page "Services Endpoints"

  2. Si vous avez plusieurs API, cliquez sur celle pour laquelle vous souhaitez voir les traces.

  3. Assurez-vous que vous êtes sur l'onglet Aperçu.

  4. Faites défiler la liste et cliquez sur Afficher les traces. La page Liste de traces de Cloud Trace s'affiche.

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.

La page Liste de traces vous permet d'explorer une trace individuelle et de voir les délais créés par ESP dans une trace.

Exemple de trace avec des délais

Pour plus d'informations sur la page Liste de traces, consultez la page Afficher les traces dans Cloud Console.

Délais créés par ESP

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

  • Un délai pour l'ensemble de la requête 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 délai QuotaControl pour vérifier si un quota est configuré sur l'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 page 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 ce faire, vous pouvez utiliser les informations figurant dans la section Délais créés par ESP ou afficher la page Liste de traces pour consulter les traces de l'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 ESP, ou que vous connaissez le processus de déploiement. Pour en savoir plus, consultez la page Déployer le backend de l'API.

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 sur la page 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.