Fehlerbehebung bei Gemini Enterprise-Datenspeichern

Auf dieser Seite erfahren Sie, wie Sie Probleme mit Gemini Enterprise-Datenspeichern diagnostizieren und beheben. Wenn ein Datenspeicher keine Informationen abrufen kann, können Sie das Problem selbst beheben, indem Sie eine zusammenhängende, schrittweise Reise zur Beobachtbarkeit durchlaufen.

Um ein vollständiges Bild eines Fehlers zu erhalten, müssen Sie wissen, wie Google Clouddie Tools zur Beobachtbarkeit zusammenarbeiten:

  • Cloud Monitoring: Erkennt, wann ein Problem auftritt. Mit diesem Tool können Sie allgemeine Trends und Fehlerraten ansehen und Benachrichtigungen für Ihre Datenspeicher einrichten.
  • Cloud Trace: Ermittelt, wo das Problem auftritt. Mit diesem Tool können Sie den Lebenszyklus einer Anfrage ansehen, Spans analysieren und genau ermitteln, welcher Schritt zu einer hohen Latenz oder einem Fehler geführt hat.
  • Cloud Logging: Erklärt, warum das Problem auftritt. Mit diesem Tool können Sie die genauen Fehlermeldungen und Nutzlasten lesen, die mit einer fehlgeschlagenen Anfrage verknüpft sind.
  • Cloud-Audit-Logs: Ermittelt, wer oder welche Richtlinie die Aktion blockiert hat. Mit diesem Tool können Sie die Einhaltung der Sicherheitsbestimmungen, Berechtigungsänderungen und Verwaltungsaktionen verfolgen, die möglicherweise zu Zugriffsverweigerungen führen.

Workflow zur Fehlerbehebung

Wenn Sie ein Problem mit einem Datenspeicher untersuchen, folgen Sie diesem sequenziellen Workflow, um die Ursache zu isolieren und zu beheben:

  1. Trends bei der Fehlerrate prüfen
  2. Die spezifische fehlgeschlagene Anfrage finden
  3. Die Fehlernutzlast ansehen
  4. Audit-Logs zur Nutzung abgleichen

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

    Zum Metrics Explorer

  2. Prüfen Sie Ihre Dashboards und die Anzahl der Datenspeicheranfragen und filtern Sie nach Tool-ID und Engine-ID. So können Sie feststellen, ob es sich um einen einmaligen Fehler oder einen weit verbreiteten systemischen Anstieg handelt, der sofortige Aufmerksamkeit erfordert.

Die spezifische fehlgeschlagene Anfrage finden

  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. Prüfen Sie das Streudiagramm auf Traces mit einem Fehlersymbol (ein rotes Ausrufezeichen) oder einer ungewöhnlich hohen Latenz.
  3. Klicken Sie auf einen Trace, um das zugehörige Gantt-Diagramm aufzurufen.
  4. Prüfen Sie den Span invoke_connector, um zu sehen, wo der Prozess ins Stocken geraten ist oder fehlgeschlagen ist.
  5. Außerdem können Sie das eindeutige Assist-Token finden, das mit einer bestimmten Anfrage verknüpft ist. Wenn Sie ein komplexes Problem an den Google Cloud Support weiterleiten müssen, geben Sie dieses Assist-Token an, um die Untersuchung zu beschleunigen.

Die Fehlernutzlast ansehen

  1. Klicken Sie im Trace Explorer auf den fehlgeschlagenen Span.
  2. Klicken Sie im Detailbereich auf Logs ansehen.
  3. Sie werden automatisch zu Cloud Logging weitergeleitet, das nach dieser genauen Anfrage gefiltert ist. Hier können Sie die Rohdaten der Log-Nutzlast lesen, um die genaue Fehlersignatur zu ermitteln (z. B. RESOURCE_EXHAUSTED oder PERMISSION_DENIED).

Audit-Logs zur Nutzung abgleichen

Wenn die Log-Nutzlast auf ein IAM-Problem, einen fehlenden Bereich oder eine Berechtigungsverweigerung hinweist, gleichen Sie sie mit Ihren Cloud-Audit-Logs ab:

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

    Zum Log-Explorer

  2. Prüfen Sie den Administratorverlauf. Prüfen Sie, ob Ihr Administrator kürzlich einen Aktionsfilter geändert oder eine erforderliche Berechtigung widerrufen hat.

Beispiel: Fehlgeschlagene Datenspeicheranfrage verfolgen

Angenommen, ein Nutzer fordert Ihren Gemini Enterprise-Agenten auf, den Status eines Jira-Problems abzurufen, aber der Agent gibt eine allgemeine Fehlermeldung zurück. So verwenden Sie den Workflow zur Beobachtbarkeit, um die Ursache zu ermitteln:

  1. Fehlertrends prüfen:Bevor Sie nach einzelnen Fehlern suchen, sollten Sie wissen, wie weit verbreitet das Problem ist. Öffnen Sie den Metrics Explorer in Cloud Monitoring und filtern Sie die Messwerte für Datenspeicheranfragen nach tool_id: get_issue. Möglicherweise sehen Sie einen massiven, plötzlichen Anstieg der RESOURCE_EXHAUSTED-Fehler. Das bestätigt, dass es sich um ein systemisches Problem handelt und nicht nur um einen einmaligen Tippfehler des Nutzers.
  2. Fehlgeschlagene Anfrage finden:Öffnen Sie den Trace Explorer und legen Sie den Zeitfilter auf die letzte Stunde fest. Im Streudiagramm sehen Sie eine Gruppe von Traces mit einem roten Fehlersymbol, das auf Fehler hinweist. Klicken Sie auf einen dieser letzten Traces, um ihn zu untersuchen.
  3. Gantt-Diagramm prüfen:Das Gantt-Diagramm visualisiert den Verlauf der Anfrage. Sie sehen einen erfolgreichen übergeordneten Span für das anfängliche Agentenrouting, aber darunter befindet sich ein fehlgeschlagener invoke_connector-Span, der speziell auf den Jira Cloud-Datenspeicher ausgerichtet ist.
  4. Zu Logs wechseln:Klicken Sie auf den fehlgeschlagenen invoke_connector-Span. Klicken Sie im Bereich „Trace-Details“ auf Logs ansehen.

  5. Ursache ermitteln:Der Log-Explorer wird geöffnet und ist bereits nach der genauen Trace-ID gefiltert. Sie können jetzt die Log-Nutzlast prüfen, die vom Datenspeicher generiert wurde, um den genauen Fehler zu ermitteln:

    
"message": "Connector Error: Cause: Failed to execute spec-based tool 'get_issue': Request failed: HTTP error 403: {\"errorMessages\":[\"permission denied: [User] does not have access to [Resource]"],\"errors\":{}}"

    In dieser Fehlermeldung der Nutzlast sehen Sie das spezifische Tool (get_issue), das fehlgeschlagen ist, und die explizite Meldung, dass der Nutzer, der die Anfrage ausführt, keinen Zugriff auf die spezifische Ressource im Zielsystem hat.

  6. Beheben:Im Abschnitt Häufige Fehler können Sie dies als Fehler „Fehlender Ressourcen-Endnutzerzugriff“ identifizieren. Der Gemini Enterprise-Agent hat erfolgreich eine Verbindung zu Jira Cloud hergestellt, aber Jira Cloud hat die Abfrage abgelehnt, weil der Nutzer keine Berechtigungen hat. Bitten Sie Ihren Jira Cloud-Administrator, dem Nutzer Zugriff auf die spezifische Ressource zu gewähren.

Häufige Fehler

Konzentrieren Sie sich beim Prüfen der Fehlernutzlasten in Cloud Logging auf die allgemeinen Fehlersignaturen. Die meisten Datenspeicherfehler können vollständig selbst behoben werden. Suchen Sie in der folgenden Liste nach dem aufgetretenen Fehler, um die Ursache zu ermitteln und ihn zu beheben.

Authentifizierungs- und Zugriffsfehler

Diese Fehler treten auf, wenn es Probleme mit Anmeldedaten, Bereichen oder Verwaltungsrichtlinien gibt, die den Zugriff auf die erforderlichen Ressourcen verhindern. Wenn diese Fehler auftreten, können Sie mit Cloud-Audit-Logs die letzten IAM-Änderungen, Aktualisierungen von Aktionsfiltern oder widerrufenen Berechtigungen debuggen.

Abgelaufenes oder ungültiges OAuth-Token

  • Fehlersignatur:HTTP request failed with status code 401 / 401 Unauthorized
  • Ursache:Das OAuth-Token ist abgelaufen oder ungültig.
  • Lösung:Autorisieren Sie den Datenspeicher in den Gemini Enterprise-Einstellungen neu, um ein neues Token zu generieren.

Tool durch einen Aktionsfilter blockiert

  • Fehlersignatur: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • Ursache:Der Administrator hat das Tool mit einem Aktionsfilter blockiert.
  • Lösung:Der Administrator muss die Zulassungsliste für Aktionen oder Tools aktualisieren.

Fehlende OAuth-Bereiche

  • Fehlersignaturen:Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted ODER Cause: Insufficient Permission
  • Ursache:Bei der Anwendungsregistrierung auf der Drittanbieterplattform fehlen die erforderlichen Bereiche.
  • Lösung:Ein Administrator muss die im Log genannten Bereiche gewähren und die App neu autorisieren.

Fehlende IAM-Projektberechtigungen

  • Fehlersignatur:Access Denied: User does not have [permission] / mcp.tools.call permission
  • Ursache: Dem Aufrufer oder Dienstkonto fehlen die erforderlichen Google Cloud IAM-Berechtigungen im Zielprojekt.
  • Lösung:Gewähren Sie dem Aufrufer die genannte IAM-Berechtigung.

Leistungs- und Drosselungsfehler

Diese Fehler werden ausgelöst, wenn das Anfragevolumen die von der Ziel-API oder dem Zieldienst festgelegten Limits überschreitet. Mit Cloud Trace können Sie genau ermitteln, wie lange diese gedrosselten Anfragen hängen, bevor sie fehlschlagen.

Drosselung der Drittanbieter-API mit Fehlercode 429

  • Fehlersignatur:Cause: Request has been rate limited
  • Ursache:Sie senden Anfragen schneller, als die Drittanbieter-API zulässt.
  • Lösung:Reduzieren Sie die Anfragerate, implementieren Sie Backoff-Strategien oder beantragen Sie eine Erhöhung des Kontingents beim Drittanbieter.

Sichtbarkeits- und Ressourcenfehler

Diese Fehler weisen darauf hin, dass die Authentifizierung zwar erfolgreich war, der Nutzer oder die Anwendung aber nicht die spezifischen Rechte hat, die angeforderten Daten anzusehen oder damit zu interagieren.

Einschränkung der Sichtbarkeit durch Drittanbieter

  • Fehlersignatur:422 ... you do not have permission to view [Resource/Users]
  • Ursache:Eine Einschränkung der Sichtbarkeit oder eine Organisationsrichtlinie auf der Drittanbieterplattform verhindert den Datenabruf.
  • Lösung:Passen Sie Ihre Mitgliedschaft in der Drittanbieterorganisation an oder reduzieren Sie das Limit Ihres Abfragebereichs.

Fehlender Ressourcen-Endnutzerzugriff

  • Fehlersignatur:permission denied: [user] does not have access to [Resource]
  • Ursache:Der Endnutzer, der die Anfrage ausführt, hat keinen Zugriff auf die spezifische Komponente oder Ressource im Zielsystem.
  • Lösung:Gewähren Sie dem Nutzer direkt im Zielsystem Zugriff auf die Ressource.

System- und serverseitige Fehler

Diese Fehler sind auf Infrastrukturprobleme, Zeitüberschreitungen oder Backend-Fehlkonfigurationen zurückzuführen und können in der Regel nicht selbst behoben werden.

Langsamer oder überlasteter Drittanbieter-Endpunkt

  • Fehlersignatur:context deadline exceeded
  • Ursache:Der Drittanbieter-Endpunkt ist langsam oder überlastet, sodass die Google-seitige Anfrage eine Zeitüberschreitung verursacht.
  • Lösung:Wiederholen Sie die Anfrage. Wenn der Fehler weiterhin auftritt, wenden Sie sich an den Google Cloud Support, um die Zeitüberschreitung zu optimieren.

Fehlkonfiguration der MCP-Server-Anmeldedatenbindung

  • Fehlersignatur:CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • Ursache:Es gibt ein serverseitiges Richtlinienproblem, bei dem die MCP-Server-Anmeldedatenbindung falsch konfiguriert ist. Dies kann nicht vom Kunden behoben werden.
  • Lösung: Wenden Sie sich an den Google Cloud Support.

Support kontaktieren

Wenn der Fehler context deadline exceeded oder CredsPermissionException weiterhin auftritt, müssen Sie möglicherweise ein Support-Ticket beim Google Cloud Support einreichen.

Um die Lösung zu beschleunigen, erfassen Sie vor dem Eröffnen eines Tickets die folgenden Artefakte aus Ihren Tools zur Beobachtbarkeit:

  • Aus Cloud Logging:Die vollständige JSON-Log-Nutzlast des Fehlers.
  • Aus Cloud Trace:Das Assist-Token und die spezifischen Spandetails (einschließlich Trace-ID), die mit der fehlgeschlagenen Anfrage verknüpft sind.
  • Aus Audit-Logs zur Nutzung:Alle relevanten Zeitstempel für IAM-Änderungen oder Richtlinienänderungen, die das Problem möglicherweise ausgelöst haben.