Activer le traçage distribué

Cette page s'applique à Apigee et à Apigee hybrid.

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 Comprendre le traçage distribué.

Pour en savoir plus sur les termes utilisés sur cette page, consultez la présentation de Cloud Trace.

Introduction

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 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, Jaeger ou un collecteur OpenTelemetry.

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 :

Phase	Point de terminaison	Flow
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.

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

S'applique à : configurations OpenTelemetry et OpenCensus.

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 :

• RESP_SENT : ce segment est ajouté après la réception d'une réponse du serveur cible. Il contient les attributs côté cible listés sous Variables dans la portée RESP_SENT.
• PROXY_POST_RESP_SENT : ce segment est ajouté une fois la réponse du proxy envoyée au client. Il contient les attributs côté proxy listés sous Variables dans la portée PROXY_POST_RESP_SENT.
• EVENT_FLOW_RESP et EVENT_FLOW_END : ces étendues sont ajoutées pour les proxys d'API qui gèrent les réponses Streaming Server-Sent Events (SSE). EVENT_FLOW_RESP marque le flux de réponse SSE (exécuté une fois par message de réponse). EVENT_FLOW_END marque la fin du flux SSE. Ces spans ne comportent actuellement pas d'attributs par défaut. Ils apparaissent dans la trace sous forme de spans nommés pour rendre les phases SSE du proxy visibles dans le rapport de traçage.

Attributs de ressources par défaut

S'applique à : OpenTelemetry uniquement. Cette section ne s'applique pas à la configuration OpenCensus.

Lorsque vous utilisez OpenTelemetry avec le protocole de trace OTLP, le runtime Apigee associe les attributs de ressource de convention sémantique OpenTelemetry suivants à chaque span émis :

Remarque : L'approche basée sur OpenTelemetry (protocole de trace OTLP) n'est compatible qu'avec Apigee (ApigeeX). Elle n'est pas compatible avec Apigee hybrid.

Attribut	Description
service.name	Valeur fixe : apigee.googleapis.com.
service.instance.id	Identifiant de l'instance du processeur de messages qui a émis le span. Omitted when the runtime pod identity is not available.
cloud.provider	Toujours gcp.
cloud.platform	Toujours gcp_apigee.
cloud.region	Région hébergeant l'environnement d'exécution Apigee, avec global comme valeur par défaut si aucune région n'est configurée.
cloud.resource_id	Chemin d'accès complet à la ressource Apigee au format /apigee.googleapis.com/organizations/ORG/environments/ENV.
gcp.apigee.organization	Nom de l'organisation Apigee.
gcp.apigee.environment	Nom de l'environnement Apigee.
gcp.project_id	ID du projet Google Cloud . Émis uniquement lorsque l'exportateur est OPEN_TELEMETRY_CLOUD_TRACE.

Types de segments

S'applique à : configurations OpenTelemetry et OpenCensus.

Apigee émet des spans avec les valeurs SpanKind suivantes :

SpanKind	Portées émises avec ce type
SERVER	Portée du proxy racine (une par invocation de proxy), représentant la requête entrante reçue par l'environnement d'exécution Apigee.
INTERNAL	Toutes les autres portées, y compris les portées de flux (par exemple, RESP_SENT et PROXY_POST_RESP_SENT) et chaque portée d'étape de règle (par exemple, AssignMessage, VerifyAPIKey, ServiceCallout, JavaScript, KeyValueMapOperations).

Apigee n'émet pas de spans CLIENT, PRODUCER ni CONSUMER. En particulier, les appels sortants d'Apigee vers le backend cible ne sont pas émis en tant que portées CLIENT distinctes. L'appel sortant est représenté dans les portées de flux INTERNAL existantes, et l'en-tête traceparent est propagé à la cible afin que le service cible puisse émettre sa propre portée SERVER et rejoindre la même trace.

Variables dans le segment RESP_SENT

Les variables suivantes sont visibles dans le segment RESP_SENT. La colonne Variable sémantique OTEL affiche le nom de la convention sémantique OpenTelemetry utilisé lorsque spanSemantics est défini sur OTEL. La colonne Attribut affiche l'ancien nom de l'attribut.

Ancienne variable	Variable sémantique OTEL	Attribut	Description
REQUEST_URL	url.full	request.url	URL complète de la requête client entrante reçue par le proxy.
REQUEST_VERB	http.request.method	request.verb	Verbe HTTP de la requête client entrante (par exemple, GET ou POST).
RESPONSE_STATUS_CODE	http.response.status_code	response.status.code	Code d'état de la réponse renvoyé par le serveur cible.
ROUTE_NAME	gcp.apigee.route.name	route.name	Nom de la règle de routage qui a sélectionné la cible pour cette requête.
ROUTE_TARGET	gcp.apigee.route.target	route.target	Nom du point de terminaison cible sélectionné par la règle de routage.
TARGET_BASE_PATH	gcp.apigee.target.basepath	target.basepath	Partie du chemin de base de l'URL cible.
TARGET_HOST	server.address	target.host	Nom d'hôte du serveur cible contacté par le proxy.
TARGET_IP	server.address	target.ip	Adresse IP résolue du serveur cible.
TARGET_NAME	gcp.apigee.target.name	target.name	Nom du point de terminaison cible défini dans le proxy d'API.
TARGET_PORT	server.port	target.port	Port TCP utilisé pour se connecter au serveur cible.
TARGET_RECEIVED_END_TIMESTAMP	gcp.apigee.target.received_end_timestamp	target.received.end.timestamp	Code temporel (en millisecondes depuis l'époque) auquel le proxy a fini de recevoir la réponse du serveur cible.
TARGET_RECEIVED_START_TIMESTAMP	gcp.apigee.target.received_start_timestamp	target.received.start.timestamp	Code temporel (en millisecondes depuis l'epoch) auquel le proxy a commencé à recevoir la réponse du serveur cible.
TARGET_SENT_END_TIMESTAMP	gcp.apigee.target.sent_end_timestamp	target.sent.end.timestamp	Code temporel (en millisecondes depuis l'epoch) auquel le proxy a terminé d'envoyer la requête au serveur cible.
TARGET_SENT_START_TIMESTAMP	gcp.apigee.target.sent_start_timestamp	target.sent.start.timestamp	Code temporel (millisecondes depuis l'epoch) auquel le proxy a commencé à envoyer la requête au serveur cible.
TARGET_SSL_ENABLED	gcp.apigee.target.ssl_enabled	target.ssl.enabled	Valeur booléenne indiquant si la connexion au serveur cible utilisait TLS.
TARGET_URL	url.full	target.url	URL complète du serveur cible contacté par le proxy.

Variables dans le segment PROXY_POST_RESP_SENT

Les variables suivantes sont visibles dans le segment PROXY_POST_RESP_SENT. La colonne Variable sémantique OTEL affiche le nom de la convention sémantique OpenTelemetry utilisé lorsque spanSemantics est défini sur OTEL. La colonne Attribut affiche l'ancien nom de l'attribut.

Ancienne variable	Variable sémantique OTEL	Attribut	Description
API_PROXY_REVISION	gcp.apigee.proxy.revision	apiproxy.revision	Numéro de révision du proxy d'API ayant géré la requête.
APIPROXY_NAME	gcp.apigee.proxy.name	apiproxy.name	Nom du proxy d'API ayant géré la requête.
CLIENT_RECEIVED_END_TIMESTAMP	gcp.apigee.client.received_end_timestamp	client.received.end.timestamp	Code temporel (en millisecondes depuis l'epoch) auquel le proxy a fini de recevoir la requête du client.
CLIENT_RECEIVED_START_TIMESTAMP	gcp.apigee.client.received_start_timestamp	client.received.start.timestamp	Code temporel (millisecondes depuis l'epoch) auquel le proxy a commencé à recevoir la requête du client.
CLIENT_SENT_END_TIMESTAMP	gcp.apigee.client.sent_end_timestamp	client.sent.end.timestamp	Code temporel (en millisecondes depuis l'époque) auquel le proxy a fini d'envoyer la réponse au client.
CLIENT_SENT_START_TIMESTAMP	gcp.apigee.client.sent_start_timestamp	client.sent.start.timestamp	Code temporel (en millisecondes depuis l'epoch) auquel le proxy a commencé à envoyer la réponse au client.
ENVIRONMENT_NAME	gcp.apigee.environment	environment.name	Nom de l'environnement Apigee dans lequel le proxy a été exécuté.
FAULT_SOURCE	gcp.apigee.fault_source	message.header.X-Apigee-fault-source	Source de la défaillance lorsqu'une erreur se produit lors de l'exécution du proxy. Renseigné uniquement dans les flux d'erreur.
IS_ERROR	gcp.apigee.is_error	is.error	Booléen indiquant si l'exécution du proxy s'est terminée par un flux d'erreur.
MESSAGE_ID	gcp.apigee.message.id	message.id	Identifiant unique attribué par Apigee à la requête, utile pour corréler les journaux et les spans de trace.
MESSAGE_STATUS_CODE	http.response.status_code	message.status.code	Code d'état de la réponse finale, y compris pour les appels sans cibles et pour les flux d'erreur.
PROXY_BASE_PATH	http.route	proxy.basepath	Chemin de base du proxy d'API correspondant à la requête entrante.
PROXY_CLIENT_IP	client.address	proxy.client.ip	Adresse IP du client qui a envoyé la requête au proxy.
PROXY_NAME	gcp.apigee.proxy.name	proxy.name	Nom du point de terminaison du proxy dans le proxy d'API qui a traité la requête.
PROXY_PATH_SUFFIX	url.path	proxy.pathsuffix	Partie du chemin de l'URL de la requête qui suit le chemin de base du proxy.
PROXY_URL	url.full	proxy.url	URL complète du point de terminaison du proxy tel qu'il a été reçu du client.

Systèmes de traçage distribué compatibles

Recommandation : Pour les nouveaux déploiements, choisissez l'une des options OpenTelemetry (Cloud Trace avec OpenTelemetry ou OpenTelemetry Collector). La compatibilité avec OpenCensus est conservée pour les configurations existantes. OpenTelemetry prend en charge des taux d'échantillonnage plus élevés (jusqu'à 100%, contre 50% sur OpenCensus), la norme W3C Trace Context et un écosystème de collecteurs plus large.

Vous pouvez configurer votre environnement d'exécution Apigee de manière à envoyer les données de trace aux systèmes de traçage distribué suivants :

Systèmes de traçage distribué	Description
Cloud Trace avec OpenTelemetry	Idéal pour les utilisateurs qui souhaitent une configuration simple avec OpenTelemetry et dont le backend de traçage principal ou unique est Cloud Trace. Pour envoyer des données de trace à Cloud Trace avec OpenTelemetry, procédez comme suit : Configurez l'environnement d'exécution Apigee pour Cloud Trace. Activez le traçage distribué pour Cloud Trace avec OpenTelemetry. Remarque : Vous êtes responsable de tous les coûts associés à l'envoi de données de trace à Cloud Trace. Pour en savoir plus, consultez les pages Tarifs et Quotas.
Collecteur OpenTelemetry	Gérez votre propre collecteur OpenTelemetry pour contrôler la collecte et le traitement des données de trace. Cette option est idéale si vous devez envoyer des données à plusieurs systèmes (y compris non Google) ou personnaliser la façon dont les données sont traitées, regroupées ou enrichies. Pour envoyer des données de trace à un collecteur OpenTelemetry, procédez comme suit : Déployez et gérez un collecteur OpenTelemetry, comme décrit dans Collecteur OpenTelemetry. Activez le traçage distribué pour un collecteur OpenTelemetry. Consultez Points à prendre en compte lors de l'utilisation d'un collecteur OpenTelemetry pour connaître les exigences en termes d'accessibilité réseau, de protocole TLS et de transport que vous devez respecter avant d'activer cette option.
Cloud Trace avec OpenCensus	Pour envoyer des données de trace à Cloud Trace avec OpenCensus, procédez comme suit : Configurer l'environnement d'exécution Apigee pour Cloud Trace (OpenCensus) Activez le traçage distribué pour Cloud Trace avec OpenCensus. Remarque : Vous êtes responsable de tous les coûts associés à l'envoi de données de trace à Cloud Trace. Pour en savoir plus, consultez les pages Tarifs et Quotas.
Jaeger avec OpenCensus	Pour envoyer des données de trace à Jaeger avec OpenCensus, activez le traçage distribué pour Jaeger.

Variables d'environnement

Les procédures de cette page utilisent les variables d'environnement suivantes. Nous vous recommandons de les définir dans votre environnement avant de commencer.

TOKEN="Authorization: Bearer $(gcloud auth application-default 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 de votre projet Google Cloud .

Configurer l'environnement d'exécution Apigee pour OpenTelemetry ou OpenCensus

Le runtime Apigee est compatible avec deux normes de traçage : OpenTelemetry (recommandée pour les nouveaux déploiements) et OpenCensus. Choisissez la norme de traçage adaptée à votre environnement, puis suivez les étapes de configuration correspondantes dans la section ci-dessous.

Pour OpenTelemetry, l'environnement d'exécution Apigee reconnaît le format d'en-tête de contexte de trace W3C, y compris les en-têtes traceparent, tracestate et baggage.

Remarque : Les en-têtes B3 ne sont pas compatibles avec OpenTelemetry. Lorsque vous configurez le runtime Apigee pour OpenTelemetry, les en-têtes de propagation B3 (par exemple, x-b3-traceid, x-b3-spanid, x-b3-sampled, x-b3-parentspanid, x-b3-flags et le formulaire à en-tête unique b3) sont ignorés, même s'ils sont présents dans la requête entrante. Seuls les en-têtes de contexte de trace W3C (traceparent, tracestate et baggage) sont pris en compte pour la propagation du contexte. Dans OpenTelemetry, les en-têtes B3 sont ignorés, qu'ils soient transmis par le client ou générés automatiquement par un maillage de services tel qu'Istio. En effet, le contexte de trace W3C est prioritaire sur B3. Les en-têtes B3 injectés par Istio sont donc également ignorés. Si vos appelants en amont n'émettent actuellement que des en-têtes B3, configurez-les pour qu'ils émettent également des traceparent W3C ou utilisez la configuration OpenCensus à la place.

Remarque : Propagation du contexte de trace sur les appels sortants. Lorsque le traçage distribué est activé, l'environnement d'exécution Apigee propage le contexte de trace actif aux requêtes sortantes effectuées par les règles et flux suivants, afin que le service en aval puisse poursuivre la même trace :

• Requêtes de point de terminaison cible (cible de backend), y compris les cibles de règles de routage
• ServiceCallout
• IntegrationCallout
• VerifyIAM
• Protection de l'IA générative (SanitizeUserPrompt et SanitizeModelResponse)
• SemanticCache (SemanticCacheLookup et SemanticCachePopulate)
• JavaScript (httpClient.send)
• ModelRouter (via la cible qu'il sélectionne)
• Diffuser des réponses d'événements envoyés par le serveur (SSE)

Pour ces règles et ces flux, Apigee propage les en-têtes de contexte de trace W3C (traceparent, tracestate et baggage) lorsque vous utilisez OpenTelemetry, et les en-têtes B3 lorsque vous utilisez OpenCensus.

Configurer les prérequis pour Cloud Trace (OpenTelemetry)

L'environnement d'exécution Apigee (ApigeeX) est compatible avec le traçage distribué à l'aide de Cloud Trace avec OpenTelemetry. Si vous utilisez un collecteur OpenTelemetry géré par le client, vous pouvez ignorer cette section et passer directement à la section Activer le traçage distribué pour un collecteur OpenTelemetry.

Remarque : Ces conditions préalables ne s'appliquent qu'à la route Cloud Trace. Elles ne s'appliquent pas à un collecteur OpenTelemetry géré par le client. Si vous utilisez un collecteur, ignorez cette section et consultez Activer le traçage distribué pour un collecteur OpenTelemetry.

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

Pour configurer votre environnement d'exécution Apigee pour Cloud Trace, les API suivantes doivent être activées pour votre projet Google Cloud  :

• API Cloud Trace (trace.googleapis.com)
• API Telemetry (telemetry.googleapis.com)
• API Service Usage (serviceusage.googleapis.com)

L'activation de ces API permet à votre projet Google Cloud de recevoir des données de trace via OpenTelemetry à partir de sources authentifiées.

Pour activer les API, procédez comme suit :

1. Dans la console Google Cloud , accédez à API et services :

   Accéder aux API et aux services

2. Cliquez sur Activer les API et les services pour ouvrir la bibliothèque d'API.
3. Dans la bibliothèque d'API, activez l'API Cloud Trace, l'API Telemetry et l'API Service Usage. Vous pouvez trouver chaque API en la recherchant par son nom (par exemple, Telemetry API) dans la barre de recherche de la bibliothèque d'API.

Remarque : L'API Telemetry est activée sur la page Bibliothèque d'API (accessible en cliquant sur Activer les API et les services), et non dans la liste API et services activés. Utilisez la barre de recherche de la bibliothèque d'API pour la trouver.

En plus d'activer les API, vous devez attribuer les rôles suivants au compte de l'agent de service :

• roles/telemetry.tracesWriter
• roles/serviceusage.serviceUsageConsumer

Le compte de service spécifique dépend de votre environnement Apigee :

• ApigeeX (non hybride) : attribuez les rôles à l'agent de service Apigee, un compte de service P4SA (par produit et par projet) géré par Google qu'Apigee provisionne automatiquement pour le projet. Le compte de l'agent de service est au format [e-mail].

Consultez Attribuer un rôle IAM à l'aide de la console Google Cloud .

Attention : Il est obligatoire d'attribuer ces rôles à l'agent de service Apigee (P4SA). Si les rôles sont manquants, le runtime Apigee ne peut pas exporter les spans et aucune donnée de trace n'atteint Cloud Trace.

Activer le traçage distribué (OpenTelemetry)

Avant d'activer le traçage distribué, créez les variables d'environnement requises.

Activer le traçage distribué pour Cloud Trace

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

1. 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":"OPEN_TELEMETRY_CLOUD_TRACE",
             "endpoint": "'"$PROJECT_ID"'",
             "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
             "traceProtocol": "OTLP",
             "spanSemantics": "OTEL"
           }'

   L'exemple de corps de requête comprend les éléments suivants :

   • Pour prendre en charge Cloud Trace avec OpenTelemetry, le paramètre exporter est défini sur OPEN_TELEMETRY_CLOUD_TRACE et le paramètre traceProtocol sur OTLP.
   • La valeur de samplingRate est définie sur 0,05. Cela signifie qu'environ 5% des appels d'API sont envoyés pour le traçage distribué. Pour OpenTelemetry, vous pouvez spécifier un taux d'échantillonnage allant jusqu'à 1.0 (100%). Pour en savoir plus, consultez Considérations sur les performances.
     Remarque : samplingRate ne s'applique qu'aux requêtes qui ne comportent pas d'en-tête traceparent W3C. Lorsqu'une requête arrive avec un en-tête traceparent, Apigee utilise l'indicateur échantillonné dans cet en-tête au lieu de l'indicateur samplingConfig local. Pour en savoir plus, consultez Priorité des en-têtes sur la configuration locale.
   • Le paramètre endpoint est défini sur l' Google Cloud ID du projet qui doit recevoir les données de trace (une simple chaîne d'ID de projet, et non une URL).
     Remarque : Le paramètre endpoint doit être défini sur le projet associé au compte de service configuré à l'étape de configuration.
     Alerte : Une fois défini, le point de terminaison du projet Cloud Trace est immuable.
   • Le paramètre spanSemantics est facultatif et contrôle l'attribut et la dénomination de la portée utilisés sur les portées émises. Valeurs acceptées :
     • LEGACY (par défaut) : utilisez les noms d'attributs et de segments Apigee historiques indiqués dans la colonne Attribut des tableaux de variables.
     • OTEL : utilisez les noms de convention sémantique OpenTelemetry indiqués dans la colonne Variable sémantique OTel. Nécessite que traceProtocol soit défini sur OTLP.

   Une réponse réussie ressemble à ceci :

   {
     "exporter": "OPEN_TELEMETRY_CLOUD_TRACE",
     "endpoint": "my-gcp-project-id",
     "samplingConfig": {
       "sampler": "PROBABILITY",
       "samplingRate": 0.05
     },
     "traceProtocol": "OTLP",
     "spanSemantics": "OTEL"
   }

Activer le traçage distribué pour un collecteur OpenTelemetry

Pour activer le traçage distribué pour un collecteur OpenTelemetry géré par le client, exécutez cet appel d'API Apigee :

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "http://my-otel-collector.example.com:4318/v1/traces",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL"
        }'

L'exemple de corps de requête comprend les éléments suivants :

• Pour prendre en charge un collecteur OpenTelemetry géré par le client, le paramètre exporter est défini sur OPEN_TELEMETRY_COLLECTOR et le paramètre traceProtocol est défini sur OTLP.
• Le paramètre endpoint est défini sur l'URL HTTP/HTTPS complète du point d'ingestion OTLP de votre collecteur OpenTelemetry (par exemple, http://my-otel-collector.example.com:4318/v1/traces). Contrairement à l'exportateur Cloud Trace, qui accepte un ID de projet Google Cloud brut, l'exportateur OPEN_TELEMETRY_COLLECTOR nécessite une URL complète incluant le schéma, l'hôte, le port et le chemin d'accès. Contrairement au point de terminaison Cloud Trace, le collecteur OpenTelemetry endpoint est mutable : vous pouvez le reconfigurer ultérieurement avec un autre PATCH pour traceConfig.
• La valeur de samplingRate est définie sur 0,05. Cela signifie qu'environ 5% des appels d'API sont envoyés pour le traçage distribué. Pour plus d'informations, consultez la section Considérations sur les performances.
  Remarque : samplingRate ne s'applique qu'aux requêtes qui ne comportent pas d'en-tête traceparent W3C. Lorsqu'une requête arrive avec un en-tête traceparent, Apigee utilise l'indicateur échantillonné dans cet en-tête au lieu de l'indicateur samplingConfig local. Pour en savoir plus, consultez Priorité des en-têtes sur la configuration locale.
• Le paramètre otelCollectorSecurityScheme est facultatif et sa valeur par défaut est NONE. Définissez-le sur MTLS pour activer le protocole TLS mutuel entre Apigee et le collecteur. Pour connaître les champs mtlsConfig requis et le corps complet de la requête API, consultez Configurer mTLS pour un collecteur OpenTelemetry.

Une réponse réussie ressemble à ceci :

{
  "exporter": "OPEN_TELEMETRY_COLLECTOR",
  "endpoint": "http://my-otel-collector.example.com:4318/v1/traces",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP",
  "spanSemantics": "OTEL"
}

Éléments à prendre en compte lors de l'utilisation d'un collecteur OpenTelemetry

Avant d'activer le traçage distribué pour un collecteur OpenTelemetry géré par le client, vérifiez les exigences suivantes.

Joignabilité du réseau

• Assurez-vous qu'Apigee peut atteindre le collecteur OpenTelemetry.
• Pour accéder à un collecteur qui n'est pas exposé sur l'Internet public, utilisez Private Service Connect (PSC).
• Si un proxy inverse est présent dans votre configuration, configurez-le sur le collecteur OpenTelemetry. Les connexions entre le processeur de messages et le collecteur OpenTelemetry sont toujours directes.

Protocole de transport

Seul le transport OTLP/HTTP est compatible avec les collecteurs OpenTelemetry (port 4318 et chemin d'accès /v1/traces selon la convention OTLP). OTLP/gRPC (port 4317) n'est pas compatible.

TLS et mTLS

Apigee est compatible avec deux schémas de sécurité pour la connexion à un collecteur OpenTelemetry, définis par le biais de otelCollectorSecurityScheme sur traceConfig :

• Aucune sécurité (HTTP) (NONE, par défaut) : Apigee se connecte au collecteur via HTTP sans TLS mutuel.
• mTLS (MTLS) : TLS mutuel, afin que le collecteur puisse également authentifier Apigee en tant que client. Pour activer l'authentification mTLS, définissez otelCollectorSecurityScheme sur MTLS dans traceConfig et fournissez un mtlsConfig qui fait référence aux keystores et truststores gérés par Apigee. Pour une configuration de bout en bout, consultez Configurer mTLS pour un collecteur OpenTelemetry.

Configurer mTLS pour un collecteur OpenTelemetry

Le protocole TLS mutuel (mTLS) permet à votre OpenTelemetry Collector d'authentifier le runtime Apigee en tant que client, en plus d'Apigee qui valide le certificat de serveur du collecteur.

Remarque : Les noms de keystore, de truststore et d'alias utilisés dans les exemples suivants (par exemple, otel-mtls, mp-client et otel-mtls-truststore) ne sont que des exemples. Vous pouvez utiliser les noms de votre choix.

Avant de configurer mTLS, vérifiez les conditions préalables suivantes :

• Votre collecteur est configuré pour exiger l'authentification par certificat client (par exemple, le paramètre tls.client_ca_file du collecteur OpenTelemetry) et est déployé avec un fichier d'autorité de certification (CA) qui contient la chaîne de certificats que vous importez à l'étape 1 de la configuration.
• endpoint utilise le schéma https://.
• exporter est défini sur OPEN_TELEMETRY_COLLECTOR et traceProtocol est défini sur OTLP. Le protocole mTLS n'est pas appliqué à l'exportateur OPEN_TELEMETRY_CLOUD_TRACE, qui s'authentifie à l'aide d'OAuth Google Cloud .

Étape 1 : Importez la clé et le certificat client

Créez un keystore pour le certificat client Apigee avec lequel le collecteur s'authentifie, puis importez la clé et le certificat en tant qu'alias :

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases?alias=mp-client&format=keycertfile" \
    -X POST \
    -F "keyFile=@client.key" \
    -F "certFile=@client.crt"

Le fichier client.crt doit être signé par une autorité de certification approuvée par le tls.client_ca_file du collecteur. Pour une configuration auto-signée, client.crt peut être le même fichier que celui utilisé par le collecteur comme client_ca_file.

Étape 2 : Importez le certificat de serveur du collecteur

Créez un truststore que le runtime Apigee utilise pour valider le certificat de serveur du collecteur, puis importez le certificat CA du collecteur en tant qu'alias CERT :

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls-truststore" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls-truststore/aliases?alias=server-ca&format=keycertfile" \
    -X POST \
    -F "certFile=@server-ca.pem"

Étape 3 : Activez mTLS sur traceConfig

PATCH le traceConfig pour définir le schéma de sécurité sur MTLS et référencer le keystore et le truststore que vous venez de créer :

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter": "OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "https://my-otel-collector.example.com:4318/v1/traces",
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL",
          "otelCollectorSecurityScheme": "MTLS",
          "mtlsConfig": {
            "keyStore":   "otel-mtls",
            "keyAlias":   "mp-client",
            "trustStore": "otel-mtls-truststore"
          }
        }'

L'objet mtlsConfig comporte trois champs obligatoires :

• keyStore : nom du keystore contenant la clé client et le certificat Apigee de l'étape 1 (par exemple, otel-mtls). Pour utiliser une référence Apigee, spécifiez ref://REFERENCE_NAME.
• keyAlias : nom de l'alias KEY_CERT dans keyStore (par exemple, mp-client).
• trustStore : nom du keystore contenant le certificat de l'autorité de certification du serveur du collecteur de l'étape 2 (par exemple, otel-mtls-truststore). Pour utiliser une référence Apigee, spécifiez ref://REFERENCE_NAME.

Apigee applique la validation suivante à traceConfig lorsque otelCollectorSecurityScheme est MTLS :

• exporter doit être OPEN_TELEMETRY_COLLECTOR.
• traceProtocol doit être OTLP.
• endpoint doit utiliser le schéma https://.
• Les trois champs mtlsConfig doivent être renseignés. Si un champ est manquant, le code HTTP 400 est renvoyé.
• Les keystores et alias référencés, ainsi que toutes les références, doivent déjà exister. Les ressources manquantes renvoient une erreur HTTP 400.

Effectuer la rotation de la clé ou du certificat client

Pour faire pivoter la clé ou le certificat client sans modifier traceConfig, importez un nouveau matériel de clé dans l'alias mp-client existant avec une requête PUT :

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases/mp-client" \
    -X PUT \
    -F "keyFile=@client-v2.key" \
    -F "certFile=@client-v2.crt"

L'environnement d'exécution Apigee détecte la modification de l'alias et de la révision lors de sa prochaine synchronisation de la configuration, puis reconstruit l'exportateur OTLP mTLS avec les nouvelles identifiants. Aucun redémarrage de pod n'est requis et aucune requête en cours n'est abandonnée.

Critères d'échantillonnage

Le runtime Apigee décide d'enregistrer ou non une trace pour chaque requête en combinant les en-têtes de requête entrants avec la configuration de trace de l'environnement.

En-tête de contexte de trace W3C

Dans la configuration OpenTelemetry, le runtime respecte l'en-tête Contexte de trace W3C traceparent. Le dernier octet de traceparent (l'octet trace-flags) contient l'indicateur sampled : la valeur 01 indique que l'appelant a déjà décidé d'enregistrer la trace, et 00 indique qu'il ne l'a pas fait.

Les recommandations de la spécification du contexte de trace W3C pour l'indicateur échantillonné conseillent à un composant de respecter l'indicateur échantillonné entrant lorsqu'il prend une décision d'enregistrement et de refléter une décision d'enregistrement définitive dans l'indicateur. Apigee suit ces recommandations : il respecte l'indicateur d'échantillonnage entrant lorsqu'il décide d'enregistrer une trace (voir Priorité de l'en-tête sur la configuration locale) et définit l'indicateur d'échantillonnage sur l'en-tête traceparent qu'il propage aux services en aval pour indiquer si la requête est enregistrée. Pour contrôler la sécurité contre le traçage indésirable déclenché par le flag entrant, définissez sampler sur OFF (voir Désactiver la configuration du traçage distribué), ce qui désactive le traçage même pour les requêtes dont traceparent est défini sur le flag "échantillonné".

Priorité des en-têtes sur la configuration locale

Lorsqu'une requête entrante comporte un en-tête traceparent, l'environnement d'exécution Apigee utilise l'indicateur échantillonné de cet en-tête au lieu de son samplingConfig local. Une requête dont l'indicateur d'échantillonnage est défini sur 01 est toujours tracée, tandis qu'une requête dont l'indicateur est défini sur 00 ne l'est pas. L'samplingConfig au niveau de l'environnement ne s'applique qu'aux requêtes qui arrivent sans en-tête traceparent.

Désactiver le traçage

Pour désactiver le traçage pour chaque proxy d'un environnement (à l'exclusion des remplacements de proxy), définissez sampler sur OFF dans le traceConfig de l'environnement. Consultez Désactiver la configuration de traçage distribué.

Remplacements par proxy

Pour n'activer le traçage que pour un sous-ensemble de proxys dans un environnement, laissez l'environnement samplingConfig avec sampler défini sur OFF et créez un remplacement par proxy (avec sampler défini sur PROBABILITY et un samplingRate non nul) pour chaque proxy que vous souhaitez tracer. Consultez Forcer les paramètres de trace pour les proxys d'API.

Impact du taux d'échantillonnage sur les performances

Le samplingRate que vous configurez a une incidence directe sur les performances d'exécution. Chaque requête échantillonnée entraîne un travail supplémentaire du processeur sur le Processeur de messages (génération et exportation de segments) et ajoute de la latence au chemin de la requête. À mesure que le taux d'échantillonnage augmente, le volume de trafic tracé par MP augmente également, ce qui peut réduire le débit et augmenter la latence de queue (p95, p99). L'impact augmente avec le volume de trafic : à de faibles taux de requêtes, la surcharge est généralement négligeable, tandis qu'à des taux de requêtes élevés, un taux d'échantillonnage élevé peut réduire considérablement le débit durable et nécessiter une capacité de MP supplémentaire. Dans les benchmarks internes, l'exécution à samplingRate=1.0 (échantillonnage à 100 %) sous un trafic soutenu et important a réduit le débit d'environ 15 % par rapport à l'exécution avec le traçage désactivé.

En règle générale, maintenez samplingRate à une valeur faible (par exemple, 0.1 ou moins) en production, et augmentez-la uniquement pour des proxys spécifiques via les remplacements par proxy lorsque vous avez besoin d'une visibilité plus approfondie. Pour obtenir une analyse détaillée de l'impact attendu et des conseils sur la capacité, consultez Considérations sur les performances.

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 de la complexité du proxy d'API (par exemple, le nombre de règles), du taux d'échantillonnage probabiliste (défini par la valeur samplingRate) et, surtout, du volume de trafic tracé par rapport à la capacité d'exportation des segments par processeur de messages (MP).

Le MP Apigee a un taux d'exportation de portée limité. Avec la configuration par défaut, un seul MP peut exporter de manière durable environ 820 spans par seconde. Une exécution de proxy d'API typique émet environ 10 étendues (préflux de proxy, flux cible, post-flux, règles associées). Un seul MP peut donc tracer de manière durable environ 82 requêtes par seconde à 100% d'échantillonnage. La mise à l'échelle du nombre d'instances répliquées du pool de nœuds de calcul augmente le plafond global de manière linéaire.

Le tableau suivant récapitule l'impact attendu à samplingRate=1.0 (probabilité de 100 %) pour deux régimes de trafic :

Remarque : Les chiffres du tableau suivant supposent que les requêtes entrantes ne comportent pas d'en-tête traceparent W3C. Les requêtes qui arrivent avec un en-tête traceparent dont l'octet d'échantillonnage est activé (1) sont toujours tracées et ont la priorité sur le samplingRate configuré, ce qui peut modifier le volume de trace effectif et l'impact sur les performances qui en résulte.

Régime de trafic (par MP)	Impact attendu à samplingRate=1.0	Action recommandée
Trafic faible (moins de 82 requêtes tracées par seconde et par MP, environ)	Le débit diminue d'environ 1 à 2 %, la latence moyenne augmente d'environ 1 % et la latence P99 augmente d'environ 15 à 20%. Négligeable en pratique.	Vous pouvez l'activer à 100 % sans risque.
Trafic dense (nettement supérieur à environ 82 requêtes tracées par seconde et par MP)	Le débit diminue d'environ 14 %, la latence moyenne augmente d'environ 24 %, la latence p75 augmente d'environ 52 % et le taux d'erreur augmente d'environ 1 point de pourcentage.	Diminuez samplingRate (par exemple, à 0.1 ou 0.05), ou augmentez le nombre de répliques de votre MP afin que chaque MP traite moins de requêtes tracées par seconde.

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 à l'aide de remplacements par proxy.

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

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

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

Pour configurer votre environnement d'exécution Apigee pour Cloud Trace, l'API Cloud Trace doit être activée pour votre projet Google Cloud .

Pour activer l'API, procédez comme suit :

1. Dans la console Google Cloud , accédez à API et services :

   Accéder aux API et aux services

2. Cliquez sur Activer les API et les services.
3. Activez l'API Cloud Trace.

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

Pour configurer l'environnement d'exécution Apigee Hybrid pour Cloud Trace, activez l'API Cloud Trace.

En plus d'activer l'API, 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 le rôle roles/cloudtrace.agent et les clés requis, procédez comme suit :

1. Créez un compte de service :

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

2. 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

3. Créez une clé de compte de service et mettez à jour votre overrides.yaml en suivant les étapes ci-dessous.
4. 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

   Les clés de compte de service constituent un risque pour la sécurité si elles ne sont pas gérées correctement. Vous êtes responsable de la sécurité de la clé privée et des autres opérations décrites dans la section Bonnes pratiques de gestion des clés de compte de service. Si vous ne parvenez pas à créer une clé de compte de service, la création de clé de compte de service peut être désactivée pour votre organisation. Pour en savoir plus, consultez la page Gérer les ressources d'organisation sécurisées par défaut.

   Si vous avez obtenu la clé de compte de service auprès d'une source externe, vous devez la valider avant de l'utiliser. Pour en savoir plus, consultez Exigences de sécurité pour les identifiants provenant de sources externes.

5. 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

6. Appliquez les modifications à l'environnement d'exécution à l'aide de Helm :

   helm upgrade ENV_NAME apigee-env/ \
       --namespace APIGEE_NAMESPACE \
       --set env=ENV_NAME \
       --atomic \
       -f overrides.yaml

Activer le traçage distribué (OpenCensus)

Avant d'activer le traçage distribué, créez les variables d'environnement requises.

Activer le traçage distribué pour Cloud Trace avec OpenCensus

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

1. 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 :

   • Pour prendre en charge Cloud Trace, le paramètre exporter est défini sur CLOUD_TRACE. Le paramètre traceProtocol, qui n'est pas spécifié, est défini par défaut sur OpenCensus.
   • Le paramètre endpoint est défini sur le projet Google Cloud dans lequel vous souhaitez envoyer la trace.
   • 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 OpenCensus, le taux d'échantillonnage maximal configurable est de 0.5.
     Avertissement : Une fois défini, le paramètre endpoint ne peut plus être modifié.

   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 avec OpenCensus

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 :

• Pour prendre en charge Jaeger, le paramètre exporter est défini sur JAEGER. Le paramètre traceProtocol, qui n'est pas spécifié, est défini par défaut sur OpenCensus.
• Le paramètre endpoint est défini sur l'emplacement où Jaeger est installé et configuré.
  Avertissement : Une fois défini, le paramètre endpoint ne peut plus être modifié.
• 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é.

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.

Pour en savoir plus, consultez Considérations sur les performances.

Remarque : Délai de propagation de la configuration. Une réponse API réussie à PATCH .../traceConfig confirme que la configuration a été acceptée par le plan de contrôle. L'environnement d'exécution Apigee interroge les mises à jour de configuration. Par conséquent, une modification est généralement appliquée à l'environnement d'exécution environ une à deux minutes après la réponse de l'API. Lorsque vous vérifiez une modification de configuration, laissez passer ce délai de propagation avant d'examiner le problème plus en détail. Utilisez les champs revisionId et updateTime renvoyés par l'API (consultez Afficher la configuration du traçage distribué) pour confirmer l'état du plan de contrôle.

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": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  },
  "revisionId": "7",
  "updateTime": "2026-06-08T14:25:13.512000Z"
}

revisionId est incrémenté à chaque mise à jour réussie, et updateTime reflète le code temporel du serveur de la modification la plus récente. Utilisez ces deux champs pour confirmer que le plan de contrôle a accepté une mise à jour de la configuration. Les deux champs sont également renvoyés par la réponse PATCH .../traceConfig.

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 -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.6}
        }'

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

{
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.6
  },
  "traceProtocol": "OTLP"
}

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

Pour mettre à jour la configuration de 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 '{
          "samplingConfig": {"sampler": "OFF"}
        }'

Remarque : Si vous définissez sampler sur OFF, le traçage est désactivé pour chaque requête dans l'environnement, y compris les requêtes qui arrivent avec un en-tête traceparent W3C dont l'indicateur d'échantillonnage est défini. Le runtime ne consulte samplingRate que lorsque sampler est défini sur PROBABILITY. Pour en savoir plus, consultez Critères d'échantillonnage.

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

{
  "samplingConfig": {
    "sampler": "OFF"
  },
  "traceProtocol": "OTLP"
}

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 :

1. 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
         }
       }
     ]
   }

2. 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 :

1. 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
         }
       }
     ]
   }

2. 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 \

Résoudre les problèmes de traçage distribué

Pour résoudre les problèmes liés au traçage distribué, procédez comme suit :

• Vérifiez la configuration du traçage distribué à l'aide de l'API traceConfig pour vous assurer qu'elle correspond à vos besoins.
• Vérifiez que le compte de service dispose des autorisations IAM (rôles) appropriées dans le projet de destination.
• Si vous utilisez Cloud Trace avec OpenTelemetry, vérifiez les segments entrants et les éventuelles erreurs d'activation de l'API ou de quota.
• Si vous utilisez un collecteur OpenTelemetry géré par le client, procédez comme suit :
  • Vérifiez qu'Apigee peut accéder au point de terminaison du collecteur. Vérifiez votre configuration Private Service Connect (PSC), le cas échéant.
  • Consultez les journaux OpenTelemetry Collector pour identifier les problèmes de données ou de connexion.
  • Assurez-vous que le certificat TLS du collecteur est valide.
• Examinez les journaux d'exécution Apigee pour détecter les erreurs d'exportation de trace.