Surveiller le trafic via Agent Gateway

Cette page explique comment afficher les journaux, surveiller les requêtes et suivre les traces distribuées pour le trafic acheminé via votre déploiement Agent Gateway.

Journalisation

Les journaux Agent Gateway sont générés à l'aide de la ressource surveillée networkservices.googleapis.com/Gateway.

Vous pouvez utiliser ces journaux pour surveiller les demandes d'accès à la passerelle. Cela inclut les journaux créés lorsque Agent Gateway est déployé en mode de simulation.

Afficher les journaux d'une passerelle spécifique

Pour afficher les journaux d'une passerelle spécifique, procédez comme suit :

Noms des journaux Agent Platform

Pour interroger des types spécifiques d'entrées de journal dans l'explorateur de journaux, vous pouvez filtrer votre requête par nom de journal à l'aide du champ logName. Le tableau suivant décrit les principaux noms de journaux générés par l'Agent Gateway et les opérations côté agent.

Remplacez PROJECT_ID par l'ID du projet Cloud de Confiance by S3NS .

Si vous utilisez Model Armor pour assainir le contenu, ces journaux sont émis séparément. Pour savoir comment interroger les journaux Model Armor, consultez Afficher les journaux bruts sur la sécurité du contenu dans l'explorateur de journaux.

Contenu consigné

Les entrées de journal de l'Agent Gateway contiennent des informations utiles pour surveiller et déboguer le trafic vers et depuis votre passerelle.

Surveillance

Agent Gateway exporte certaines métriques de Service Extensions vers Cloud Monitoring. Si vous déléguez l'autorisation aux Service Extensions, vous pouvez utiliser ces métriques pour surveiller le trafic vers et depuis votre extension. Pour en savoir plus, consultez Journalisation et surveillance des callouts Cloud Load Balancing.

Tableau de bord Observabilité

Agent Gateway fournit un tableau de bord d'observabilité qui vous permet de surveiller, d'auditer et de déboguer le trafic routé via vos passerelles :

• Tableaux de données : suivez le nombre total de tentatives d'autorisation, d'échecs d'autorisation et de requêtes par seconde.
• Graphiques : visualisez les taux d'échec d'autorisation (%) et les requêtes par seconde au fil du temps.
• Journaux du trafic sortant : consultez les journaux détaillés des requêtes sortantes, y compris les refus 403, le trafic vers les points de terminaison non enregistrés et les tendances générales du trafic.

Procédez comme suit pour accéder au tableau de bord d'observabilité d'une passerelle dans la console Cloud de Confiance  :

1. Dans la console Cloud de Confiance , accédez à la page Agent Gateway.

   Accéder à Agent Gateway

2. Cliquez sur le nom de la passerelle que vous souhaitez surveiller.

3. Cliquez sur l'onglet Observabilité.

Exigences concernant les données du tableau de bord

Le tableau de bord d'observabilité Agent Gateway utilise l'analyse de l'observabilité pour afficher les données. Si le tableau de bord ne charge pas les données, assurez-vous de mettre à niveau le bucket de journaux _Default pour utiliser l'Analyse de l'observabilité. Le tableau de bord récupère les données de la vue _AllLogs du bucket _Default.

Utiliser Cloud Trace

Agent Gateway s'intègre à Cloud Trace pour fournir une observabilité de bout en bout des requêtes pour les charges de travail des agents. Étant donné que la passerelle d'agent sert de point de contrôle central pour les agents d'IA, l'activation du traçage vous permet de voir comment les requêtes transitent de vos agents à la passerelle et à travers plusieurs services Cloud de Confiance , outils, agents et serveurs MCP. En suivant les flux de requêtes au-delà de ces limites de service, Trace fournit un traçage distribué complet pour vos architectures d'agents.

Trace vous permet d'effectuer les opérations suivantes :

• Déboguez les interactions de l'agent avec précision : suivez l'intégralité du parcours d'une requête au-delà des limites de service pour isoler les goulots d'étranglement de latence et les appels de backend en échec.
• Respecter les décisions d'échantillonnage en amont : utilisez l'échantillonnage basé sur le parent pour maintenir la continuité du traçage de bout en bout lorsque des agents ou des clients en amont lancent le traçage. Cela permet de s'assurer que les requêtes à haute priorité sont entièrement capturées sans augmenter les taux d'échantillonnage de référence pour le trafic de routine.
• Unifiez l'observabilité avec des normes ouvertes : les traces sont basées sur les normes OpenTelemetry et W3C TraceContext. Elles propagent de manière transparente le contexte dans vos agents IA, votre Agent Gateway, vos outils ou serveurs MCP cibles, et vos plates-formes de surveillance tierces.
• Accélérez l'analyse des causes premières : corrélez directement les spans de trace avec les journaux et les métriques des requêtes de passerelle à l'aide de trace_id pour résoudre plus rapidement les problèmes de production.

Pour en savoir plus sur Trace, consultez la présentation de Cloud Trace.

Rôles requis

Vous devez disposer des rôles Identity and Access Management (IAM) suivants dans votre projet :

• Pour configurer et mettre à jour une stratégie de traçage : Administrateur de réseau Compute (roles/compute.networkAdmin) ou Administrateur Compute (roles/compute.admin)
• Pour afficher les traces dans la console Cloud de Confiance  : Utilisateur Cloud Trace (roles/cloudtrace.user)

De plus, pour permettre à Agent Gateway d'écrire des spans de trace dans Trace, vous devez accorder le rôle Agent Cloud Trace (roles/cloudtrace.agent) aux comptes de service suivants :

• Agent de service Compute Engine : service-PROJECT_NUMBER@compute-system.s3ns-system.iam.gserviceaccount.com
• Agent de service de sécurité réseau : service-PROJECT_NUMBER@gcp-sa-networksecurity.s3ns-system.iam.gserviceaccount.com
• Agent de service Agent Gateway : service-PROJECT_NUMBER@gcp-sa-agentgateway.s3ns-system.iam.gserviceaccount.com
• Compte de service de l'agent ou de la charge de travail client : si l'agent d'IA ou la charge de travail client appelant lance la trace et exporte ses propres étendues parentes vers Trace, le compte de service de la charge de travail ou le compte de service personnalisé associé à l'agent doivent également disposer du rôle roles/cloudtrace.agent sur le projet. Sinon, seule l'étendue enfant de l'Agent Gateway est écrite et l'étendue parente sera manquante dans Trace.

Remplacez PROJECT_NUMBER par le numéro de votre projet Cloud de Confiance .

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

Activer le traçage

Pour activer le traçage pour Agent Gateway, créez un fichier YAML de stratégie d'observabilité et importez-le à l'aide de gcloud CLI.

1. Créez un fichier de configuration nommé tracing-policy.yaml :

   name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/POLICY_NAME"
   telemetryTarget:
     resources: # You can attach a policy to multiple gateways
     - "//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME"
   displayName: "Tracing policy for Agent Gateway traffic"
   tracingConfiguration:
     samplingRate: SAMPLING_RATE
     parentBasedSampling:
       enabled: ENABLE_PARENT_BASED_SAMPLING
       samplingRate: PARENT_BASED_SAMPLING_RATE
   

   Remplacez les éléments suivants :

   • PROJECT_ID : ID de votre projet Cloud de Confiance .
   • REGION : région de votre passerelle (par exemple, europe-west1).
   • POLICY_NAME : nom de la stratégie d'observabilité (par exemple, my-agw-tracing-policy).
   • AGENT_GATEWAY_NAME : nom de votre passerelle.
   • SAMPLING_RATE : fraction des requêtes à tracer. Définissez une valeur comprise entre 0.0 et 1.0. Pour les environnements de production à trafic élevé, nous recommandons un taux de 1% (0.01) ou 0,1% (0.001) afin d'équilibrer l'observabilité et les coûts d'ingestion.
   • ENABLE_PARENT_BASED_SAMPLING : contrôle si le bit échantillonné doit être respecté dans les en-têtes traceparent entrants des appelants en amont. Définissez cette valeur sur true ou false.
   • PARENT_BASED_SAMPLING_RATE : fraction des requêtes pré-échantillonnées à tracer. Définissez une valeur comprise entre 0.0 et 1.0. Par exemple, 1.0 trace 100% des requêtes pré-échantillonnées.

2. Importez la règle d'observabilité :

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

Afficher les traces

Après avoir activé le traçage distribué et envoyé du trafic via votre passerelle, vous pouvez afficher les détails de la trace dans la console Cloud de Confiance  :

1. Dans la console Cloud de Confiance , accédez à la page  Explorateur Trace :

   Accéder à Explorateur Trace

   Vous pouvez également accéder à cette page à l'aide de la barre de recherche.

2. Dans la barre Filtre, saisissez une expression de filtre de trace (par exemple, pour filtrer par seuil de latence, code d'état HTTP ou URI de la demande) ou recherchez l'ID de trace spécifique.

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

   Explorateur Trace

   

   Vue chronologique des traces

   

   Vue graphique des traces

   

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

Agent Gateway permet de corréler facilement les traces, les journaux et les métriques :

• Corrélation entre les journaux et les traces : chaque entrée de journal des requêtes de passerelle écrite dans Cloud Logging contient un champ trace au format projects/PROJECT_ID/traces/TRACE_ID.

  • Dans l'explorateur de journaux, cliquez sur l'entrée de journal, puis sélectionnez Afficher les détails de la trace pour accéder directement à la portée correspondante dans Trace.
  • Dans Trace, cliquez sur Afficher les journaux dans le volet Détails de la trace pour afficher tous les journaux des requêtes de passerelle associés à cette requête.

• Corrélation des métriques : comparez les pics de latence observés dans les métriques Cloud Monitoring, telles que networkservices.googleapis.com/agentgateway/total_latencies, avec les répartitions des spans de trace pour identifier si un pic de latence s'est produit au niveau de la passerelle ou de l'outil ou du serveur de destination.

Dépannage

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

• Les traces n'apparaissent pas dans Cloud Trace :

  1. Vérifiez que l'API Cloud Trace (cloudtrace.googleapis.com) est activée dans votre projet :

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

  2. Vérifiez que les rôles IAM d'agent Cloud Trace (roles/cloudtrace.agent) requis ont été attribués à tous les comptes de service requis.

  3. Vérifiez que la règle d'observabilité existe dans la bonne région et qu'elle fait référence à la passerelle Agent Gateway appropriée :

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

  4. Vérifiez le samplingRate configuré. Si le volume de trafic ou le taux d'échantillonnage sont faibles, il est possible que les traces ne soient pas capturées immédiatement. Pour vérifier que le traçage fonctionne, vous pouvez mettre à jour temporairement votre règle pour utiliser un échantillonnage à 100 % (samplingRate: 1.00). Une fois le test terminé, restaurez votre taux de production.

• Délais de trace incomplets :

  Si les portées de trace apparaissent comme des traces racines indépendantes ou déconnectées au lieu d'être des portées enfants de vos requêtes d'application, procédez comme suit :

  1. Vérifiez que parentBasedSampling est activé (défini sur true) dans votre règle d'observabilité.
  2. Vérifiez que le rôle Agent Cloud Trace (roles/cloudtrace.agent) a été attribué au compte de service de l'agent IA ou de la charge de travail appelant sur le projet afin que les segments parents puissent être exportés vers Trace.
  3. Vérifiez que votre application utilise un SDK OpenTelemetry dont la propagation du contexte de traçage distribué est activée. L'en-tête traceparent W3C est ainsi propagé au-delà des limites de service. Pour en savoir plus, consultez la documentation sur le propagateur TraceContext OpenTelemetry.

Étapes suivantes