Activer le traçage distribué

Vous consultez la documentation d'Apigee X.
Consultez la documentation d'Apigee Edge.

Cette page présente les étapes requises pour configurer le traçage distribué pour votre environnement d'exécution Apigee. Si vous débutez avec les systèmes de traçage distribué et que vous souhaitez en savoir plus, consultez la page Qu'est-ce que le traçage distribué ?

Présentation

Les systèmes de traçage distribués vous permettent de suivre une requête dans un système logiciel distribué sur plusieurs applications, services et bases de données, ainsi que sur des intermédiaires comme des proxys. Ces systèmes de traçage génèrent des rapports indiquant le temps pris par une requête à chaque étape. Les rapports de traçage peuvent également fournir une vue précise des différents services appelés lors d'une requête, ce qui vous permet de mieux comprendre ce qui se passe à chaque étape dans votre système logiciel.

L'outil de traçage dans Apigee Edge et l'outil de débogage dans Apigee X sont utiles pour dépanner et surveiller vos proxys d'API. Toutefois, ces outils n'envoient aucune donnée aux serveurs de traçage distribué tels que Cloud Trace ou Jaeger. Pour afficher les données d'exécution Apigee dans un rapport de traçage distribué, vous devez activer explicitement le traçage distribué dans votre environnement d'exécution Apigee. Une fois le traçage activé, l'environnement d'exécution peut envoyer des données de trace aux serveurs de traçage distribué et participer à une trace existante. Vous pouvez ainsi afficher les données provenant de l'intérieur et de l'extérieur de votre écosystème Apigee à partir d'un seul emplacement.

Vous pouvez afficher les informations suivantes dans vos rapports de traçage distribué :

Temps d'exécution d'un flux entier
Heure à laquelle la requête est reçue
Heure à laquelle la requête est envoyée à la cible
Heure à laquelle la réponse est reçue de la cible
Temps d'exécution de chaque règle dans un flux
Temps d'exécution des appels de service et des flux cibles
Heure à laquelle la réponse est envoyée au client

Dans votre rapport de traçage distribué, vous pouvez afficher les détails de l'exécution des flux sous forme de segments. Un segment fait référence au temps pris par un flux dans une trace. Le temps nécessaire à l'exécution d'un flux est affiché sous forme de cumul du temps nécessaire à l'exécution de chaque règle dans le flux. Vous pouvez afficher chacun des flux suivants sous forme de segments individuels :

Requête
- Proxy
  - Preflow
  - PostFlow
- Cible
  - Preflow
  - PostFlow
Réponse
- Proxy
  - Preflow
  - PostFlow
- Cible
  - Preflow
  - PostFlow

Une fois le traçage distribué activé, l'environnement d'exécution Apigee trace par défaut un ensemble de variables prédéfinies. Pour en savoir plus, consultez la section Variables de trace par défaut dans le rapport de traçage. Vous pouvez utiliser la règle TraceCapture pour étendre le comportement d'exécution par défaut et tracer des variables supplémentaires de flux, de règle ou personnalisées. Pour en savoir plus, consultez la section sur la règle TraceCapture.

Un appel d'API entrant vers Apigee peut contenir des en-têtes de trace, car l'appel fait partie d'une trace existante. Dans ce cas, Apigee participe à la trace existante et propage les en-têtes à l'appel d'API sortant. L'environnement d'exécution Apigee est compatible avec le format d'en-tête Zipkin B3. Par conséquent, il reconnaît les en-têtes x-b3-traceid, x-b3-spanid et x-b3-sampled lorsqu'ils participent à une trace existante. Toutefois, s'il n'y a pas d'en-têtes de trace dans un appel d'API entrant, Apigee ajoute ses en-têtes de trace et les propage à l'appel d'API sortant. D'autres services peuvent accéder aux en-têtes et participer au traçage, si nécessaire.

Variables de trace par défaut dans le rapport de traçage

Une fois le traçage distribué activé, vous pouvez afficher l'ensemble de variables prédéfinies suivant dans le rapport de traçage. Les variables sont visibles dans les segments suivants :

POST_RESP_SENT : ce segment est ajouté après la réception d'une réponse du serveur cible.
POST_CLIENT_RESP_SENT : ce segment est ajouté une fois la réponse du proxy envoyée au client.

Variables dans le segment POST_RESP_SENT

Les variables suivantes sont visibles dans le segment POST_RESP_SENT :

REQUEST_URL (request.url)
REQUEST_VERB (request.verb)
RESPONSE_STATUS_CODE (response.status.code)
ROUTE_NAME (route.name)
ROUTE_TARGET (route.target)
TARGET_BASE_PATH (target.basepath)
TARGET_HOST (target.host)
TARGET_IP (target.ip)
TARGET_NAME (target.name)
TARGET_PORT (target.port)
TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
TARGET_SSL_ENABLED (target.ssl.enabled)
TARGET_URL (target.url)

Variables dans le segment POST_CLIENT_RESP_SENT

Les variables suivantes sont visibles dans le segment POST_CLIENT_RESP_SENT :

API_PROXY_REVISION (apiproxy.revision)
APIPROXY_NAME (apiproxy.name)
CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
ENVIRONMENT_NAME (environment.name)
FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
IS_ERROR (is.error)
MESSAGE_ID (message.id)
MESSAGE_STATUS_CODE (message.status.code)
PROXY_BASE_PATH (proxy.basepath)
PROXY_CLIENT_IP (proxy.client.ip)
PROXY_NAME (proxy.name)
PROXY_PATH_SUFFIX (proxy.pathsuffix)
PROXY_URL (proxy.url)

Systèmes de traçage distribué compatibles

L'environnement d'exécution Apigee est compatible avec les systèmes de traçage distribué suivants :

Cloud Trace
Jaeger

Vous pouvez configurer votre environnement d'exécution Apigee de manière à envoyer les données de trace à un système Cloud Trace ou Jaeger.

Étant donné que le traçage de tous les appels d'API dans l'environnement d'exécution d'Apigee aurait un impact sur les performances, Apigee vous permet de configurer un taux d'échantillonnage probabiliste. En utilisant le taux d'échantillonnage, vous pouvez spécifier le nombre d'appels d'API envoyés pour le traçage distribué. Par exemple, si vous spécifiez le taux d'échantillonnage 0.4, cela signifie que 40 % des appels d'API sont envoyés pour le traçage. Pour plus d'informations, consultez la section Considérations sur les performances.

Le taux d'échantillonnage maximal configurable est de 0.5.

Configurer des environnements d'exécution Apigee pour Cloud Trace

L'environnement d'exécution Apigee X et l'environnement d'exécution Apigee hybrid sont compatibles avec le traçage distribué à l'aide de Cloud Trace. Si vous utilisez Jaeger, vous pouvez ignorer cette section et passer directement à la section Activer le traçage distribué pour Jaeger.

Configurer l'environnement d'exécution Apigee X pour Cloud Trace

Pour utiliser Cloud Trace avec un environnement d'exécution Apigee X, l'API Cloud Trace doit être activée pour votre projet Google Cloud. Ce paramètre permet à votre projet Google Cloud de recevoir des données de trace provenant de sources authentifiées.

Pour vérifier que l'API Cloud Trace est activée, procédez comme suit :

Dans Google Cloud Console, accédez à API et services :
Accéder aux API et aux services
Cliquez sur Activer les API et les services.
Dans la barre de recherche, saisissez API Trace.
Si l'option API activée est affichée, cette API est déjà activée et vous n'avez rien à faire. Sinon, cliquez sur Activer.

Configurer l'environnement d'exécution Apigee Hybrid pour Cloud Trace

Pour utiliser Cloud Trace avec un environnement d'exécution Apigee hybrid, vous devez activer l'API Cloud Trace. Pour vérifier que l'API Cloud Trace est activée, suivez les étapes décrites dans la section Configurer l'environnement d'exécution Apigee X pour Cloud Trace.

En plus d'activer l'API Cloud Trace, vous devez ajouter le compte de service iam.gserviceaccount.com pour utiliser Cloud Trace avec l'environnement d'exécution hybride. Pour ajouter le compte de service, ainsi que les rôles et les clés requis, procédez comme suit :

Créez un compte de service :

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

Ajoutez une liaison de stratégie IAM à un compte de service :

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/cloudtrace.agent --project PROJECT_ID

Créez une clé de compte de service :

gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com

Ajoutez le compte de service au fichier overrides.yaml.

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

Appliquez les modifications à l'environnement d'exécution

apigeectl apply -f overrides.yaml --env=ENV_NAME

Activer le traçage distribué

Avant d'activer le traçage distribué pour Cloud Trace ou Jaeger, créez les variables d'environnement suivantes :

TOKEN="Authorization: Bearer $(gcloud auth print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

Où :

TOKEN définit l'en-tête d'authentification avec un jeton de support. Vous utiliserez cet en-tête pour appeler les API Apigee. Pour en savoir plus, consultez la page de référence sur la commande print-access-token.
ENV_NAME est nom d'un environnement dans votre organisation
PROJECT_ID est l'ID du projet Google Cloud.

Activer le traçage distribué pour Cloud Trace

L'exemple suivant montre comment activer le traçage distribué pour Cloud Trace :

Exécutez l'appel d'API Apigee suivant :
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{"exporter":"CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'",
    "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
```
L'exemple de corps de requête comprend les éléments suivants :
- La valeur de samplingRate est définie sur 0,1. Cela signifie qu'environ 10 % des appels d'API sont envoyés pour le traçage distribué. Pour en savoir plus sur la définition d'une valeur samplingRate pour votre environnement d'exécution, consultez la section Considérations sur les performances.
- Le paramètre exporter est défini sur CLOUD_TRACE.
- Le point de terminaison est défini sur le projet Google Cloud dans lequel vous souhaitez envoyer la trace. REMARQUE : Il doit correspondre au compte de service utilisé à l'étape de configuration.
Une réponse réussie ressemble à ceci :
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

Activer le traçage distribué pour Jaeger

L'exemple suivant montre comment activer le traçage distribué pour Jaeger :

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

Dans cet exemple :

La valeur de samplingRate est définie sur 0,4. Cela signifie qu'environ 40 % des appels d'API sont envoyés pour le traçage distribué.
Le paramètre exporter est défini sur JAEGER.
Le point de terminaison est défini sur l'emplacement où Jaeger est installé et configuré.

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

Afficher la configuration de traçage distribué

Pour afficher la configuration de traçage distribué existante dans votre environnement d'exécution, connectez-vous à votre environnement d'exécution, puis exécutez la commande suivante :

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

Mettre à jour la configuration de traçage distribué

La commande suivante indique comment mettre à jour la configuration de traçage distribué existante pour Cloud Trace :

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

Dans cet exemple, le taux d'échantillonnage est mis à jour et passe à 0.05.

Pour mettre à jour la configuration pour Jaeger, définissez le champ exporter de la requête sur JAEGER.

Désactiver la configuration de traçage distribué

L'exemple suivant montre comment désactiver le traçage distribué configuré pour Cloud Trace :

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH -d '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "OFF",
    "samplingRate": 0.1
  }
}

Forcer les paramètres de trace pour les proxys d'API

Lorsque vous activez le traçage distribué dans votre environnement d'exécution Apigee, tous les proxys d'API de l'environnement d'exécution utilisent la même configuration pour le traçage. Toutefois, vous pouvez remplacer la configuration de traçage distribué pour un proxy d'API ou un groupe de proxys d'API. Cela vous offre un contrôle plus précis sur la configuration de traçage.

L'exemple suivant remplace la configuration de traçage distribué pour le proxy d'API hello-world :

curl -s -H "$TOKEN" \
     'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV_NAME/traceConfig/overrides' \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

Vous pouvez remplacer la configuration pour résoudre les problèmes spécifiques à un proxy d'API sans avoir à modifier la configuration de tous les proxys d'API.

Mettre à jour les forçages de paramètres de trace

Pour mettre à jour le forçage d'une configuration de traçage pour un proxy d'API ou un groupe de proxys d'API, procédez comme suit :

Utilisez la commande suivante pour récupérer les forçages existants de la configuration de traçage :

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

Cette commande doit renvoyer une réponse semblable à la suivante, qui contient un champ "nom" qui identifie le ou les proxys régis par le forçage :

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

Pour mettre à jour le proxy, utilisez la valeur du champ "nom" pour envoyer une requête POST à la configuration de forçage de ce proxy, ainsi que les valeurs de champ mises à jour. Exemple :

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X POST \
    -H "content-type:application/json" \
    -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

Supprimer les forçages de paramètres de trace

Pour supprimer un forçage de configuration de traçage pour un proxy d'API ou un groupe de proxys d'API, procédez comme suit :

Utilisez la commande suivante pour récupérer les forçages existants de la configuration de traçage :

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

Cette commande doit renvoyer une réponse semblable à la suivante, qui contient un champ "nom" qui identifie le ou les proxys régis par le forçage :

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

Pour supprimer le proxy, utilisez la valeur du champ "nom" pour envoyer une requête de suppression à la configuration de forçage de ce proxy, ainsi que les valeurs de champ mises à jour. Exemple :
```
curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X DELETE \
```

Considérations sur les performances

L'activation du traçage distribué pour un environnement d'exécution Apigee a un impact attendu sur les performances. Cela peut entraîner une augmentation de l'utilisation de la mémoire, des besoins en processeur et de la latence. L'ampleur de l'impact dépend en partie de la complexité du proxy d'API (par exemple, le nombre de règles) et du taux d'échantillonnage probabiliste (défini par la valeur samplingRate). Plus le taux d'échantillonnage est élevé, plus l'impact sur les performances est important. Bien que l'impact sur les performances dépende d'un certain nombre de facteurs, vous pouvez vous attendre à une baisse de 10 à 20 % des performances lors de l'utilisation du traçage distribué.

Pour les environnements à trafic élevé et présentant des exigences de faible latence, le taux d'échantillonnage probabiliste recommandé est inférieur ou égal à 10 %. Si vous souhaitez utiliser le traçage distribué pour résoudre des problèmes, envisagez d'augmenter l'échantillonnage probabiliste (samplingRate) uniquement pour des proxys d'API spécifiques.