Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Tracer le trafic entrant avec Cloud Trace

Ce document explique comment configurer le traçage distribué pour les équilibreurs de charge d'application à l'aide de Cloud Trace. Vous créez une stratégie de télémétrie qui cible la règle de transfert de votre équilibreur de charge, puis vous affichez les traces obtenues dans Cloud Trace.

Les exemples de ce document utilisent une application d'e-commerce dont l'architecture est la suivante :

Un équilibreur de charge d'application externe global qui reçoit le trafic client pour une vitrine Web.
Un équilibreur de charge d'application interne régional qui achemine les demandes de paiement de la vitrine vers les services internes de panier, d'inventaire et de paiement.

Pour en savoir plus sur le fonctionnement du traçage distribué, y compris les modes d'échantillonnage et la gestion des en-têtes de contexte de trace, consultez Présentation du traçage distribué.

Avant de commencer

Activez l'API Cloud Trace et l'API Network Services dans votre projet :

gcloud services enable \
    cloudtrace.googleapis.com \
    networkservices.googleapis.com

Assurez-vous d'avoir déployé un équilibreur de charge compatible. Pour en savoir plus, consultez les ressources suivantes :
Remarque : Les équilibreurs de charge d'application classiques ne sont pas compatibles avec le traçage distribué.
Notez le nom et le champ d'application de la règle de transfert de votre équilibreur de charge. Le champ d'application de la règle de transfert dépend du type d'équilibreur de charge :
- Règle de transfert globale : utilisée par les équilibreurs de charge d'application externes globaux et les équilibreurs de charge d'application internes interrégionaux.
- Règle de transfert régionale : utilisée par les équilibreurs de charge d'application externes régionaux et les équilibreurs de charge d'application internes régionaux.
Pour lister les règles de transfert de votre projet, utilisez la commande gcloud compute forwarding-rules list :
```
gcloud compute forwarding-rules list
```

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer des stratégies de télémétrie et afficher des traces, demandez à votre administrateur de vous accorder les rôles IAM (Identity and Access Management) suivants sur votre projet :

Pour créer, mettre à jour ou supprimer des stratégies de télémétrie : Administrateur de réseaux Compute (roles/compute.networkAdmin) ou Administrateur Compute (roles/compute.admin)
Pour afficher les traces dans la console Google Cloud : Utilisateur Cloud Trace (roles/cloudtrace.user)

Pour permettre à l'équilibreur de charge d'écrire des segments de trace dans Cloud Trace, attribuez le rôle d'agent Cloud Trace (roles/cloudtrace.agent) sur votre projet aux comptes de service suivants :

Agent de service Compute Engine : service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
Agent de service de sécurité réseau : service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
Les comptes de service de vos charges de travail de backend, si vos backends exportent leurs propres segments vers Cloud Trace. Sans ce rôle, Cloud Trace n'affiche que l'intervalle de l'équilibreur de charge, et la trace ne contient pas d'intervalles de backend.

Remplacez PROJECT_NUMBER par votre numéro de projetGoogle Cloud .

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Configuration de la stratégie de télémétrie

Vous définissez une stratégie de télémétrie dans un fichier YAML au format suivant :

name: "projects/PROJECT_ID/locations/LOCATION/telemetryPolicies/POLICY_NAME"
displayName: "DISPLAY_NAME"
telemetryTarget:
  resources:
  - "FORWARDING_RULE_URI"
tracingConfiguration:
  samplingRate: SAMPLING_RATE
  parentBasedSampling:
    enabled: ENABLE_PARENT_BASED_SAMPLING
    samplingRate: PARENT_BASED_SAMPLING_RATE

Le tableau suivant décrit les champs d'une stratégie de télémétrie :

Champs	Description
`name`	Nom de ressource de la stratégie de télémétrie. Remplacez les éléments suivants : `PROJECT_ID` : ID de votre projet Google Cloud . `LOCATION` : emplacement de la stratégie de télémétrie, qui doit correspondre au champ d'application des règles de transfert ciblées par la stratégie. Pour les règles de transfert globales, utilisez `global`. Pour les règles de transfert régionales, utilisez la région de la règle de transfert, par exemple `us-central1`. `POLICY_NAME` : nom de la stratégie de télémétrie. Le nom doit comporter entre 4 et 63 caractères, commencer par une lettre minuscule, ne contenir que des lettres minuscules, des chiffres et des traits d'union, et se terminer par une lettre minuscule ou un chiffre.
`displayName`	Facultatif. Nom lisible par l'humain (`DISPLAY_NAME`) de la stratégie de télémétrie.
`telemetryTarget.resources`	Liste des noms de ressources complets (`FORWARDING_RULE_URI`) des règles de transfert auxquelles la stratégie s'applique. Vous pouvez spécifier jusqu'à 50 ressources. Utilisez l'un des formats suivants : Règle de transfert globale : `//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME` Règle de transfert régionale : `//compute.googleapis.com/projects/PROJECT_ID/regions/REGION/forwardingRules/FORWARDING_RULE_NAME` Remplacez les éléments suivants : `FORWARDING_RULE_NAME` : nom de la règle de transfert. `REGION` : région de la règle de transfert, par exemple `us-central1`
`tracingConfiguration.samplingRate`	Proportion de requêtes à tracer (`SAMPLING_RATE`), spécifiée sous la forme d'une valeur comprise entre `0.0` (0 %) et `1.0` (100 %). Par exemple, `0.01` échantillonne 1 % des requêtes. La valeur par défaut est `0.0`.
`tracingConfiguration.parentBasedSampling.enabled`	Facultatif. Indique si l'équilibreur de charge respecte l'indicateur d'échantillonnage dans l'en-tête W3C `traceparent` entrant (`ENABLE_PARENT_BASED_SAMPLING`) est `true` ou `false`. La valeur par défaut est `false`. Compatible uniquement avec les équilibreurs de charge d'application internes.
`tracingConfiguration.parentBasedSampling.samplingRate`	Facultatif. Proportion de requêtes échantillonnées en amont à tracer (`PARENT_BASED_SAMPLING_RATE`), spécifiée sous la forme d'une valeur comprise entre `0.0` et `1.0`. Par exemple, `1.0` effectue le traçage de toutes les requêtes qu'un client ou un service en amont a déjà échantillonnées.

Configurer le traçage pour un équilibreur de charge externe

Cet exemple configure l'échantillonnage probabiliste sur la règle de transfert d'un équilibreur de charge d'application externe global pour une vitrine d'e-commerce. Un taux d'échantillonnage de 0.01 trace 1 % des requêtes, ce qui permet de capturer la latence et les erreurs de périphérie tout en maintenant les coûts d'ingestion de Cloud Trace à un niveau prévisible en cas de trafic élevé.

Créez un fichier YAML nommé storefront-tracing-policy.yaml :
```
cat <<EOF > storefront-tracing-policy.yaml
name: "projects/PROJECT_ID/locations/global/telemetryPolicies/storefront-tracing-policy"
displayName: "Tracing policy for the storefront load balancer"
telemetryTarget:
  resources:
    - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME"
tracingConfiguration:
  samplingRate: 0.01
EOF
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projetGoogle Cloud
- FORWARDING_RULE_NAME : nom de la règle de transfert globale de votre équilibreur de charge
Pour un équilibreur de charge d'application externe régional, remplacez global dans le nom de la stratégie par la région de la règle de transfert, puis utilisez le format de règle de transfert régional.

Importez la stratégie de télémétrie à l'aide de la commande gcloud beta network-services telemetry-policies import :

gcloud beta network-services telemetry-policies import storefront-tracing-policy \
    --source=storefront-tracing-policy.yaml \
    --location=global

Configurer le traçage pour un équilibreur de charge interne

Cet exemple configure un équilibreur de charge d'application interne régional pour les services de paiement et de règlement internes. La règle utilise les paramètres d'échantillonnage suivants :

Une valeur de référence samplingRate de 0.01 (1 %) pour les requêtes qui ne comportent pas de décision d'échantillonnage en amont.
Échantillonnage basé sur le parent avec un samplingRate de 1.0 (100 %), de sorte que chaque requête de paiement déjà échantillonnée au niveau de la vitrine ou par un service en amont soit tracée via l'équilibreur de charge interne.

Pour configurer la règle, procédez comme suit :

Créez un fichier YAML nommé checkout-tracing-policy.yaml :
```
cat <<EOF > checkout-tracing-policy.yaml
name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/checkout-tracing-policy"
displayName: "Tracing policy for the internal checkout load balancer"
telemetryTarget:
  resources:
    - "//compute.googleapis.com/projects/PROJECT_ID/regions/REGION/forwardingRules/FORWARDING_RULE_NAME"
tracingConfiguration:
  samplingRate: 0.01
  parentBasedSampling:
    enabled: true
    samplingRate: 1.0
EOF
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projetGoogle Cloud
- REGION : région de la règle de transfert, par exemple us-central1
- FORWARDING_RULE_NAME : nom de la règle de transfert régionale de votre équilibreur de charge
Pour un équilibreur de charge d'application interne interrégional, utilisez global comme emplacement dans le nom de la règle et utilisez le format de règle de transfert global.

Importez la stratégie de télémétrie :

gcloud beta network-services telemetry-policies import checkout-tracing-policy \
    --source=checkout-tracing-policy.yaml \
    --location=REGION

Vérifier la stratégie de télémétrie

Pour vérifier que la stratégie de télémétrie existe et cible les bonnes règles de transfert, utilisez la commande gcloud beta network-services telemetry-policies describe :

gcloud beta network-services telemetry-policies describe POLICY_NAME \
    --location=LOCATION

Remplacez les éléments suivants :

POLICY_NAME : nom de la stratégie de télémétrie.
LOCATION : global ou région de la stratégie de télémétrie

Pour lister toutes les stratégies de télémétrie d'un emplacement, utilisez la commande gcloud beta network-services telemetry-policies list :

gcloud beta network-services telemetry-policies list \
    --location=LOCATION

Mettre à jour une stratégie de télémétrie

Pour modifier les paramètres d'échantillonnage ou appliquer la même règle à d'autres règles de transfert, procédez comme suit :

Modifiez le fichier YAML de la règle. Par exemple, pour appliquer la règle de vitrine à plusieurs règles de transfert globales, ajoutez chaque règle de transfert à la liste telemetryTarget.resources :

telemetryTarget:
  resources:
    - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/storefront-https-fr"
    - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/cart-https-fr"

Importez la stratégie mise à jour :

gcloud beta network-services telemetry-policies import POLICY_NAME \
    --source=POLICY_FILE \
    --location=LOCATION

Remplacez POLICY_FILE par le chemin d'accès au fichier YAML de votre règle.

Afficher les traces

Après avoir configuré le traçage et envoyé du trafic via votre équilibreur de charge, affichez les traces dans la console Google Cloud :

Dans la console Google Cloud , accédez à la page Explorateur Trace.

Accéder à l'explorateur Trace
Sélectionnez votre projet Google Cloud .
Dans le champ Filtre, saisissez un filtre pour trouver les traces que vous souhaitez inspecter. Par exemple, l'ID d'attribut ou le seuil de latence.
Si vous le souhaitez, pour explorer une trace spécifique, accédez à la barre d'outils, cliquez sur ID de trace, puis saisissez l'ID de trace.
Cliquez sur une trace pour afficher ses segments dans les vues de chronologie et de graphique.
Inspectez le segment de l'équilibreur de charge pour afficher des détails tels que la durée totale et le backend qui a traité la requête.

Pour en savoir plus sur l'utilisation de l'explorateur de traces, consultez Rechercher et explorer des traces.

Corréler les traces avec les journaux et les métriques

Vous pouvez corréler les délais de trace de l'équilibreur de charge avec les journaux de requêtes et les métriques pour isoler la source de la latence ou des erreurs.

Corréler les traces avec les journaux

Si vous activez la journalisation sur votre service de backend, l'équilibreur de charge ajoute un champ trace à chaque entrée de journal de requête pour une requête échantillonnée. Le champ utilise le format suivant :

projects/PROJECT_ID/traces/TRACE_ID

Afficher une trace à partir d'une entrée de journal d'équilibreur de charge

Dans la console Google Cloud , accédez à la page Explorateur de journaux.

Accéder à l'explorateur de journaux
Développez une entrée de journal de l'équilibreur de charge.
Dans le résumé de l'entrée de journal, cliquez sur l'icône de trace.
Sélectionnez Afficher les détails de la trace.

La trace s'ouvre sur la page Explorateur Trace.

Afficher les journaux de l'équilibreur de charge à partir d'une trace

Dans la console Google Cloud , accédez à la page Explorateur Trace.

Accéder à l'explorateur Trace
Cliquez sur une trace pour ouvrir le volet Détails.
Cliquez sur View logs (Afficher les journaux).

Les entrées de journal de l'équilibreur de charge pour la requête s'affichent.

Corréler des traces avec des métriques

Comparez les pics de latence dans les métriques de l'équilibreur de charge avec les répartitions des segments de trace pour déterminer si la latence provient de l'équilibreur de charge ou du backend. Vous pouvez afficher et interroger ces métriques dans l'explorateur de métriques de Cloud Monitoring. Utilisez les métriques suivantes :

Équilibreur de charge d'application externe global : loadbalancing.googleapis.com/https/total_latencies et loadbalancing.googleapis.com/https/backend_latencies
Équilibreur de charge d'application externe régional : loadbalancing.googleapis.com/https/external/regional/total_latencies
Équilibreur de charge d'application interne : loadbalancing.googleapis.com/https/internal/total_latencies

Désactiver le traçage

Pour arrêter de tracer les requêtes d'un équilibreur de charge, effectuez l'une des opérations suivantes :

Supprimez la règle de transfert de la liste telemetryTarget.resources de la stratégie, puis importez la stratégie mise à jour.
Supprimez la stratégie de télémétrie à l'aide de la commande gcloud beta network-services telemetry-policies delete :
```
gcloud beta network-services telemetry-policies delete POLICY_NAME \
    --location=LOCATION
```

Bonnes pratiques

Tenez compte des bonnes pratiques suivantes lorsque vous configurez le traçage distribué :

Dimensionnez les taux d'échantillonnage en fonction de votre volume de trafic : pour les charges de travail de production à trafic élevé, utilisez un samplingRate de 0.01 (1 %) ou 0.001 (0,1 %) pour équilibrer l'observabilité avec les coûts d'ingestion de Cloud Trace.
Utilisez l'échantillonnage basé sur le parent pour les architectures multiniveaux : sur les équilibreurs de charge d'application internes, activez l'échantillonnage basé sur le parent afin que les requêtes échantillonnées en amont soient tracées à chaque saut interne.
Instrumentez vos backends : utilisez un SDK OpenTelemetry avec l'outil de propagation de contexte de trace W3C dans vos services de backend afin que les segments de backend rejoignent la trace démarrée par l'équilibreur de charge.

Résoudre les problèmes

Cette section décrit les problèmes courants et leurs solutions.

Les traces n'apparaissent pas dans Cloud Trace

Si les traces n'apparaissent pas dans Cloud Trace, procédez comme suit :

Assurez-vous que l'API Cloud Trace est activée dans votre projet :

gcloud services enable cloudtrace.googleapis.com \
    --project=PROJECT_ID

Vérifiez que le rôle d'agent Cloud Trace (roles/cloudtrace.agent) est attribué aux comptes de service listés dans Rôles requis.
Vérifiez que la stratégie de télémétrie existe au bon emplacement et qu'elle cible la bonne règle de transfert. Pour en savoir plus, consultez Vérifier la stratégie de télémétrie.
Vérifiez le samplingRate configuré. Si le volume de trafic ou le taux d'échantillonnage est faible, l'équilibreur de charge peut ne pas capturer les traces immédiatement. Pour vérifier que le traçage fonctionne, définissez temporairement samplingRate sur 1.0, puis restaurez votre taux de production lorsque vous avez terminé les tests.

Les segments de trace sont déconnectés ou incomplets

Si les segments de l'équilibreur de charge apparaissent en tant que traces racines distinctes au lieu de faire partie des traces de votre application, procédez comme suit :

Pour les équilibreurs de charge d'application internes, vérifiez que l'échantillonnage basé sur le parent est activé (parentBasedSampling.enabled: true) dans la stratégie de télémétrie.
Vérifiez que les comptes de service de vos charges de travail client et backend disposent du rôle d'agent Cloud Trace (roles/cloudtrace.agent) afin que leurs segments puissent être exportés vers Cloud Trace.
Vérifiez que vos applications utilisent un SDK OpenTelemetry avec la propagation du contexte de trace W3C activée, afin que l'en-tête traceparent soit propagé au-delà des limites du service. Pour en savoir plus, consultez la documentation sur la propagation du contexte OpenTelemetry.