Traffic über das Agent Gateway beobachten

Auf dieser Seite erfahren Sie, wie Sie Logs aufrufen, Anfragen überwachen und verteilte Traces für Traffic verfolgen, der über Ihre Agent Gateway-Bereitstellung weitergeleitet wird.

Cloud Logging

Agent Gateway-Logs werden mit der überwachten Ressource networkservices.googleapis.com/Gateway generiert.

Mit diesen Logs können Sie Zugriffsanfragen an das Gateway überwachen. Dazu gehören auch die Logs, die erstellt werden, wenn das Agent Gateway im Probelaufmodus bereitgestellt wird. Wenn Sie Logs zu Verstößen im Probelauf für Unified Access Policies (UAPs) von Identity-Aware Proxy (IAP), semantische Governance-Richtlinien, Model Armor und VPC Service Controls abfragen und einen konsolidierten Bericht zu „wäre blockiert worden“ erstellen möchten, lesen Sie Richtlinienverstöße im Probelauf über verschiedene Kontrollen hinweg prüfen.

Logs für ein bestimmtes Gateway aufrufen

So rufen Sie die Logs für ein bestimmtes Gateway auf:

Console-Abfrage

  1. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

    Zum Log-Explorer

  2. Klicken Sie auf den Umschalter Abfrage anzeigen.

  3. Alternativ können Sie Folgendes in das Abfragefeld einfügen.

    resource.type="networkservices.googleapis.com/Gateway"
    resource.labels.location="REGION"
    resource.labels.gateway_name="AGENT_GATEWAY_NAME"
    

    Ersetzen Sie Folgendes:

    • REGION: Die Region Ihres Gateways.
    • AGENT_GATEWAY_NAME: Der Name Ihres Gateways.
  4. Klicken Sie auf Abfrage ausführen.

Agent Platform-Lognamen

Wenn Sie im Log-Explorer bestimmte Arten von Logeinträgen abfragen möchten, können Sie Ihre Abfrage mit dem Feld logName nach Logname filtern. In der folgenden Tabelle werden die primären Lognamen beschrieben, die vom KI-Agenten-Gateway und von agentenseitigen Vorgängen generiert werden:

Logname Beschreibung
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests Logs für Gateway-Entscheidungen zum Zulassen und Ablehnen.
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access Cloud-Audit-Logs für IAP-AuthorizeUser-Entscheidungen.
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr Start- und Ausführungsfehler auf Agentenseite (Reasoning Engine stderr).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout Standardausgabe auf Agentenseite (Reasoning Engine stdout).

Ersetzen Sie dabei PROJECT_ID durch die ID Ihres Projekts in Google Cloud .

Wenn Sie Model Armor für die Inhaltsbereinigung verwenden, werden diese Logs separat ausgegeben. Eine Anleitung zum Abfragen von Model Armor-Logs finden Sie unter Rohprotokolle zur Inhaltssicherheit im Log-Explorer ansehen.

Was wird protokolliert?

Agent Gateway-Logeinträge enthalten Informationen, die für das Monitoring und die Fehlerbehebung bei Traffic zu und von Ihrem Gateway nützlich sind.

Feld Feldformat Feldtyp: Erforderlich oder optional Beschreibung
Schweregrad
insertID
Zeitstempel
receiveTimestamp
trace
traceSampled
logName
LogEntry Erforderlich Die allgemeinen Felder, wie in einem Logeintrag beschrieben.
httpRequest HttpRequest Erforderlich Ein gängiges Protokoll für Logging von HTTP-Anfragen
resource MonitoredResource Erforderlich

MonitoredResource ist der mit einem Logeintrag verknüpfte Ressourcentyp. Der Ressourcentyp für das KI-Agenten-Gateway ist networkservices.googleapis.com/Gateway.

jsonPayload object (Struct format) Erforderlich

Nutzlast des Logeintrags, die als JSON-Objekt ausgedrückt wird. Das JSON-Objekt enthält die folgenden Agent Gateway-Felder:

  • agentGatewayInfo: Enthält Informationen zu Agent Gateway-Anfragen.

    • mcpInfo: Enthält Informationen zur MCP-Methode der Anfrage (z. B. „tools/list“ oder „tools/call“) und den primären Parameter, der mit der Methode verknüpft ist, falls vorhanden. Bei der Methode „tools/call“ ist der Parameter beispielsweise der Toolname.
    • agentRegistryResource: Der Agent Registry-Ressourcenname des MCP-Servers, KI-Agenten oder Endpunkts, der mit der Anfrage übereinstimmt.
  • Sie können auch die Details des Felds serviceExtensionsInfo prüfen, um Informationen zur Autorisierungserweiterung (IAP, Model Armor oder andere) zu erhalten, die die Anfrage verarbeitet hat.

Latenz bei der Richtlinienweitergabe und Logaufnahme

Wenn Sie Gateway-Zugriffsregeln aktualisieren oder Sicherheitsereignisse untersuchen, sollten Sie die folgenden Zeitfenster für die Weitergabe und Aufnahme berücksichtigen:

  • Verbreitung von Unified Access Policies (UAPs): Aktualisierungen von UAPs, die von Agent Gateway erzwungen werden (z. B. das Hinzufügen einer DENY-Regel oder das Ändern von iamEnforcementMode von "DRY_RUN" zu "ENFORCE"), sind letztendlich konsistent. Direkte Richtlinienänderungen werden in der Regel innerhalb von 2 Minuten wirksam, es kann jedoch 7 Minuten oder länger dauern, bis sie global weitergegeben werden (siehe Zugriffsänderungsverteilung). Es kann einige Minuten bis Stunden dauern, bis Änderungen an der Mitgliedschaft in einer principalSet synchronisiert werden.
  • Notfallstopp des Traffics: UAP-Regeln werden bei neuen Autorisierungsprüfungen im Agent Gateway ausgewertet und beenden keinen Agent-Container oder erzwingen das Schließen bereits hergestellter Streamingverbindungen. Wenn Sie einen kompromittierten oder fehlerhaften Agenten während eines aktiven Vorfalls sofort stoppen möchten, löschen Sie die Agent-Laufzeit oder leiten Sie den Traffic der Version um. Wenden Sie außerdem eine Gateway-Ablehnungsregel an. Eine Anleitung finden Sie unter Not-Aus und Widerruf des Zugriffs.
  • Latenz für Logs, Traces und Ergebnisse: Das Agent Gateway wertet IAP- und Model Armor-Richtlinien synchron im Anfragepfad aus und schreibt networkservices.googleapis.com/gateway_requests- und cloudaudit.googleapis.com/data_access-Logeinträge (AuthorizeUser) nahezu in Echtzeit (normalerweise innerhalb von Sekunden im Log-Explorer suchbar). In Trace exportierte verteilte Trace-Spans werden ebenfalls innerhalb von Sekunden nach Abschluss des Spans angezeigt, während Out-of-Band-Bedrohungserkennungen von der Agent-Anomalieerkennung asynchron ausgewertet werden (siehe Latenz von Telemetrie- und Sicherheitsergebnissen).

Gateway-Audit-Logs aufbewahren und in ein SIEM exportieren

Wenn Sie die Zugriffsentscheidungen des Agent Gateways als manipulationssichere Compliance-Nachweise aufbewahren und das Bedrohungsmonitoring zentralisieren möchten, können Sie Ihre Logging-Buckets sperren und Gateway-Logs an eine SIEM-Plattform (Security Information and Event Management) streamen:

  • Manipulationssichere Aufbewahrung (gesperrte Log-Buckets): Leiten Sie networkservices.googleapis.com/gateway_requests- und cloudaudit.googleapis.com/data_access-Logs an einen benutzerdefinierten Logging-Bucket mit einem konfigurierten Aufbewahrungszeitraum (--retention-days) weiter und sperren Sie den Bucket dauerhaft (gcloud logging buckets update BUCKET_ID --location=LOCATION --locked), um einen WORM-konformen Speicher (Write-Once, Read-Many) zu erzwingen. Eine detaillierte Anleitung finden Sie unter Manipulationssichere Aufbewahrung für Audit-Logs.
  • SIEM-Export: Erstellen Sie eine Logsenke (oder eine aggregierte Senke auf Organisationsebene) mit einem „Einschließen“-Filter für logName:("networkservices.googleapis.com%2Fgateway_requests" OR "cloudaudit.googleapis.com%2Fdata_access"), um Gateway-Zulassungs- und Ablehnungsentscheidungen kontinuierlich nach Google Security Operations (Google SecOps), Pub/Sub (für die Aufnahme in SIEM-Drittanbieter), BigQuery oder Cloud Storage zu exportieren. Befehle zum Erstellen von Senken mit der gcloud CLI und Filterbeispiele finden Sie unter Audit-Logs in ein SIEM exportieren.

Cloud Monitoring

Das Agent-Gateway exportiert einige Service Extensions-Messwerte nach Monitoring. Wenn Sie die Autorisierung an Service Extensions delegieren, können Sie diese Messwerte verwenden, um den Traffic zu und von Ihrer Erweiterung zu überwachen. Weitere Informationen finden Sie unter Logging und Monitoring für Cloud Load Balancing-Callouts.

Observability-Dashboard

Agent Gateway bietet ein Dashboard zur Beobachtbarkeit, mit dem Sie den über Ihre Gateways geleiteten Traffic überwachen, prüfen und Fehler beheben können:

  • Kurzübersichten: Hier können Sie die Gesamtzahl der Autorisierungsversuche, Autorisierungsfehler und Anfragen pro Sekunde verfolgen.
  • Diagramme: Visualisieren Sie die Autorisierungsfehlerraten (%) und die Anfragen pro Sekunde im Zeitverlauf.
  • Logs für ausgehenden Traffic: Hier finden Sie detaillierte Logs für ausgehende Abfragen, einschließlich 403-Ablehnungen, Traffic zu nicht registrierten Endpunkten und allgemeine Traffic-Trends.

So rufen Sie das Beobachtbarkeits-Dashboard für ein Gateway in der Google Cloud Console auf:

  1. Rufen Sie in der Google Cloud Console die Seite Agent Gateway auf.

    Zu Agent Gateway

  2. Klicken Sie auf den Namen des Gateways, das Sie überwachen möchten.

  3. Klicken Sie auf den Tab Beobachtbarkeit.

Anforderungen an Dashboard-Daten

Das Dashboard für die Beobachtbarkeit des Agent-Gateways verwendet Observability Analytics, um Daten anzuzeigen. Wenn das Dashboard keine Daten lädt, müssen Sie ein Upgrade des Log-Buckets _Default durchführen, um Observability Analytics zu verwenden. Das Dashboard ruft Daten aus der _AllLogs-Ansicht des Buckets _Default ab.

Cloud Trace verwenden

Das Agent-Gateway ist in Cloud Trace eingebunden, um eine End-to-End-Beobachtbarkeit von Anfragen für Agent-Arbeitslasten zu ermöglichen. Da Agent Gateway als zentraler Kontrollpunkt für KI-Agenten dient, erhalten Sie durch die Aktivierung von Trace Einblick in den Weg von Anfragen von Ihren Agenten über das Gateway und über mehrere Google Cloud -Dienste, Tools, Agenten und MCP-Server hinweg. Durch das Verfolgen von Anfrageflüssen über diese Dienstgrenzen hinweg bietet Trace ein vollständiges verteiltes Tracing für Ihre Agent-Architekturen.

Mit Trace können Sie Folgendes tun:

  • Agenteninteraktionen präzise debuggen: Verfolgen Sie den gesamten Weg einer Anfrage über Dienstgrenzen hinweg, um Latenzengpässe und fehlerhafte Backend-Aufrufe zu isolieren.
  • Upstream-Stichprobenentscheidungen berücksichtigen: Verwenden Sie übergeordnete Stichproben, um die End-to-End-Trace-Kontinuität aufrechtzuerhalten, wenn Upstream-Agents oder -Clients das Tracing initiieren. So wird sichergestellt, dass Anfragen mit hoher Priorität vollständig erfasst werden, ohne dass die Baseline-Stichprobenraten für Routine-Traffic erhöht werden.
  • Beobachtbarkeit mit offenen Standards vereinheitlichen: Traces basieren auf den Standards OpenTelemetry und W3C TraceContext und geben den Kontext nahtlos an Ihre KI-Agenten, das Agent Gateway, Ziel-MCP-Server oder ‑Tools und Monitoring-Plattformen von Drittanbietern weiter.
  • Ursachenanalyse beschleunigen: Korrelieren Sie Trace-Spans direkt mit Gateway-Anfragelogs und -Messwerten mithilfe von trace_id, um Produktionsprobleme schneller zu beheben.

Weitere Informationen zu Trace finden Sie unter Cloud Trace – Übersicht.

Erforderliche Rollen

Sie benötigen die folgenden IAM-Rollen (Identity and Access Management) für Ihr Projekt:

  • Zum Konfigurieren und Aktualisieren einer Tracing-Richtlinie: Compute-Netzwerkadministrator (roles/compute.networkAdmin) oder Compute-Administrator (roles/compute.admin)
  • Traces in der Google Cloud Console ansehen: Cloud Trace-Nutzer (roles/cloudtrace.user)

Damit Agent Gateway Trace-Spans in Trace schreiben kann, müssen Sie den folgenden Dienstkonten die Rolle „Cloud Trace-Agent“ (roles/cloudtrace.agent) zuweisen:

  • Compute Engine-Dienst-Agent: service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
  • Netzwerksicherheits-Dienst-Agent: service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
  • Agent Gateway-Dienst-Agent: service-PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com
  • Dienstkonto für KI-Agenten- oder Client-Arbeitslasten: Wenn der aufrufende KI-Agent oder die Client-Arbeitslast den Trace initiiert und seine eigenen übergeordneten Spans in Trace exportiert, muss dem Dienstkonto der Arbeitslast oder dem benutzerdefinierten Dienstkonto, das dem KI-Agenten zugeordnet ist, auch die Rolle roles/cloudtrace.agent für das Projekt zugewiesen werden. Andernfalls wird nur der untergeordnete Agent Gateway-Span geschrieben und der übergeordnete Span fehlt in Trace.

Ersetzen Sie PROJECT_NUMBER durch die Projektnummer in Google Cloud .

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Tracing aktivieren

Wenn Sie das Tracing für das Agent-Gateway aktivieren möchten, erstellen Sie eine YAML-Datei für die Beobachtbarkeitsrichtlinie und importieren Sie sie mit der gcloud CLI.

  1. Erstellen Sie eine Konfigurationsdatei mit dem Namen 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
    

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Google Cloud Projekt-ID
    • REGION: Die Region Ihres Gateways (z. B. europe-west1).
    • POLICY_NAME: Ein Name für die Beobachtbarkeitsrichtlinie (z. B. my-agw-tracing-policy).
    • AGENT_GATEWAY_NAME: Der Name Ihres Gateways.
    • SAMPLING_RATE: Der Anteil der Anfragen, die verfolgt werden sollen. Legen Sie einen Wert zwischen 0.0 und 1.0 fest. Für Produktionsumgebungen mit hohem Traffic empfehlen wir eine Rate von 1 % (0.01) oder 0,1 % (0.001), um ein ausgewogenes Verhältnis zwischen Beobachtbarkeit und Aufnahmekosten zu erreichen.
    • ENABLE_PARENT_BASED_SAMPLING: Steuert, ob das Stichprobenbit in eingehenden traceparent-Headern von Upstream-Aufrufern berücksichtigt werden soll. Legen Sie dafür true oder false fest.
    • PARENT_BASED_SAMPLING_RATE: Der Anteil der vorab ausgewählten Anfragen, die verfolgt werden sollen. Legen Sie einen Wert zwischen 0.0 und 1.0 fest. 1.0 verfolgt beispielsweise 100 % der vorab ausgewählten Anfragen.
  2. Importieren Sie die Beobachtbarkeitsrichtlinie:

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

Traces ansehen

Nachdem Sie verteiltes Tracing aktiviert und Traffic über Ihr Gateway gesendet haben, können Sie sich die Trace-Details in der Google Cloud Console ansehen:

  1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:

    Zum Trace Explorer

    Sie können diese Seite auch über die Suchleiste finden.

  2. Geben Sie in der Filterleiste einen Trace-Filterausdruck ein (z. B. um nach Latenzschwellenwert, HTTP-Statuscode oder Anfrage-URI zu filtern) oder suchen Sie nach der spezifischen Trace-ID.

    Weitere Informationen zur Verwendung der Trace Explorer-Benutzeroberfläche finden Sie unter Traces suchen und untersuchen.

    Trace-Explorer

    Trace-Explorer-Ansicht in Trace
    Trace Explorer-Ansicht in Trace

    Trace-Zeitachsenansicht

    Zeitachsenansicht in Trace
    Zeitachsenansicht in Trace

    Trace-Diagrammansicht

    Diagrammansicht in Trace
    Grafikansicht in Trace

Traces mit Logs und Messwerten korrelieren

Agent Gateway bietet eine nahtlose Korrelation zwischen Traces, Logs und Messwerten:

  • Log-Trace-Korrelation: Jeder Gateway-Anfrage-Logeintrag, der in Logging geschrieben wird, enthält ein trace-Feld im Format projects/PROJECT_ID/traces/TRACE_ID.

    • Klicken Sie im Log-Explorer auf den Logeintrag und wählen Sie dann Trace-Details ansehen aus, um direkt zum entsprechenden Span in Trace zu gelangen.
    • Klicken Sie in Trace im Bereich Trace-Details auf Logs anzeigen, um alle Gateway-Anfragelogs aufzurufen, die mit dieser Anfrage verknüpft sind.
  • Messwertkorrelation: Vergleichen Sie Latenzspitzen, die in Monitoring-Messwerten wie networkservices.googleapis.com/agentgateway/total_latencies beobachtet wurden, mit Trace-Span-Aufschlüsselungen, um festzustellen, ob eine Latenzspitze innerhalb des Gateways oder am Zieltool oder ‑server aufgetreten ist.

Fehlerbehebung

In diesem Abschnitt werden häufige Probleme und ihre Lösungen beschrieben.

  • Traces werden in Cloud Trace nicht angezeigt:

    1. Prüfen Sie, ob die Cloud Trace API (cloudtrace.googleapis.com) in Ihrem Projekt aktiviert ist:

      gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
      
    2. Prüfen Sie, ob allen erforderlichen Dienstkonten die erforderlichen Cloud Trace-Agent-IAM-Rollen (roles/cloudtrace.agent) zugewiesen wurden.

    3. Prüfen Sie, ob die Beobachtbarkeitsrichtlinie in der richtigen Region vorhanden ist und auf das entsprechende Agent Gateway-Gateway verweist:

      gcloud beta network-services telemetry-policies describe POLICY_NAME \
          --location=REGION
      
    4. Prüfen Sie die konfigurierte samplingRate. Wenn das Traffic-Volumen oder die Abtastrate niedrig ist, werden Traces möglicherweise nicht sofort erfasst. Wenn Sie prüfen möchten, ob das Tracing funktioniert, können Sie Ihre Richtlinie vorübergehend so aktualisieren, dass 100 % der Stichproben (samplingRate: 1.00) verwendet werden. Stellen Sie die Produktionsrate wieder her, wenn Sie mit dem Testen fertig sind.

  • Unvollständige Trace-Spans:

    Wenn Trace-Spans als unabhängige oder getrennte Root-Traces anstelle von untergeordneten Spans Ihrer Anwendungsanfragen angezeigt werden, gehen Sie so vor:

    1. Prüfen Sie, ob parentBasedSampling in Ihrer Beobachtbarkeitsrichtlinie aktiviert (auf true gesetzt) ist.
    2. Prüfen Sie, ob dem Dienstkonto des aufrufenden KI-Agenten oder der Arbeitslast die Rolle „Cloud Trace-Agent“ (roles/cloudtrace.agent) für das Projekt zugewiesen wurde, damit übergeordnete Spans nach Trace exportiert werden können.
    3. Prüfen Sie, ob Ihre Anwendung ein OpenTelemetry SDK verwendet, für das die Weitergabe des verteilten Trace-Kontexts aktiviert ist, damit der W3C-traceparent-Header über Dienstgrenzen hinweg weitergegeben wird. Weitere Informationen finden Sie in der Dokumentation zum OpenTelemetry-TraceContext-Propagator.

Nächste Schritte

Codelab

Hier erfahren Sie, wie Sie agentische Arbeitslasten mit Agent Gateway auf der Gemini Enterprise Agent Platform verwalten.

Fehlerbehebung

Informationen zur Fehlerbehebung bei der Verbindung zum KI-Agenten-Gateway.