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
Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.
Klicken Sie auf den Umschalter Abfrage anzeigen.
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.
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 |
|
| 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:
|
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 voniamEnforcementModevon"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 einerprincipalSetsynchronisiert 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- undcloudaudit.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- undcloudaudit.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:
Rufen Sie in der Google Cloud Console die Seite Agent Gateway auf.
Klicken Sie auf den Namen des Gateways, das Sie überwachen möchten.
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.agentfü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.
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_RATEErsetzen Sie Folgendes:
PROJECT_ID: Ihre Google Cloud Projekt-IDREGION: 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 zwischen0.0und1.0fest. 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 eingehendentraceparent-Headern von Upstream-Aufrufern berücksichtigt werden soll. Legen Sie dafürtrueoderfalsefest.PARENT_BASED_SAMPLING_RATE: Der Anteil der vorab ausgewählten Anfragen, die verfolgt werden sollen. Legen Sie einen Wert zwischen0.0und1.0fest.1.0verfolgt beispielsweise 100 % der vorab ausgewählten Anfragen.
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:
-
Rufen Sie in der Google Cloud Console die Seite
Trace Explorer auf:
Sie können diese Seite auch über die Suchleiste finden.
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-Zeitachsenansicht
Zeitachsenansicht in Trace Trace-Diagrammansicht
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 Formatprojects/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_latenciesbeobachtet 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:
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
Prüfen Sie, ob allen erforderlichen Dienstkonten die erforderlichen Cloud Trace-Agent-IAM-Rollen (
roles/cloudtrace.agent) zugewiesen wurden.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=REGIONPrü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:
- Prüfen Sie, ob
parentBasedSamplingin Ihrer Beobachtbarkeitsrichtlinie aktiviert (auftruegesetzt) ist. - 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. - 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.
- Prüfen Sie, ob
Nächste Schritte
Codelab: Agentische Arbeitslasten mit der Agent Platform verwalten
Hier erfahren Sie, wie Sie agentische Arbeitslasten mit Agent Gateway auf der Gemini Enterprise Agent Platform verwalten.
Fehlerbehebung für Agent Gateway
Informationen zur Fehlerbehebung bei der Verbindung zum KI-Agenten-Gateway.