Memecahkan masalah penyimpanan data Gemini Enterprise

Gunakan halaman ini untuk mendiagnosis dan menyelesaikan masalah apa pun terkait penyimpanan data Gemini Enterprise. Jika penyimpanan data gagal mengambil informasi, Anda dapat men-debug masalah tersebut secara mandiri dengan mengikuti perjalanan kemampuan observasi yang kohesif dan bertahap.

Untuk mendapatkan gambaran lengkap tentang error, pahami cara kerja alat kemampuan observasi Google Cloudbersama-sama:

  • Cloud Monitoring: Mendeteksi kapan masalah terjadi. Gunakan fitur ini untuk melihat tren tingkat tinggi, rasio error, dan menyiapkan pemberitahuan untuk penyimpanan data Anda.
  • Cloud Trace: Menemukan tempat terjadinya masalah. Gunakan alat ini untuk melihat siklus proses permintaan, menganalisis span, dan mengidentifikasi dengan tepat langkah mana yang menyebabkan latensi tinggi atau kegagalan.
  • Cloud Logging: Menjelaskan alasan masalah terjadi. Gunakan alat ini untuk membaca pesan error dan payload yang tepat terkait permintaan yang gagal.
  • Cloud Audit Logs: Mengidentifikasi siapa atau kebijakan apa yang memblokir tindakan. Gunakan alat ini untuk melacak kepatuhan keamanan, perubahan izin, dan tindakan administratif yang mungkin menyebabkan penolakan akses.

Alur kerja proses debug

Saat menyelidiki masalah penyimpanan data, ikuti alur kerja berurutan ini untuk mengisolasi dan menyelesaikan akar masalah:

  1. Memeriksa tren rasio error
  2. Menemukan permintaan tertentu yang gagal
  3. Melihat payload error
  4. Melakukan referensi silang log audit penggunaan

  1. Di konsol Google Cloud , buka halaman Metrics Explorer.

    Buka Metrics Explorer

  2. Periksa dasbor Anda dan tinjau jumlah permintaan penyimpanan data Anda, lalu filter menurut Tool ID dan Engine ID. Anda dapat menentukan apakah masalah tersebut merupakan error satu kali atau lonjakan sistemik yang meluas dan memerlukan perhatian segera.

Menemukan permintaan tertentu yang gagal

  1. Di konsol Google Cloud , buka halaman Trace explorer:

    Buka Trace explorer

    Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

  2. Periksa diagram sebar untuk menemukan trace dengan ikon error (tanda seru merah) atau latensi yang sangat tinggi.
  3. Klik rekaman aktivitas untuk melihat diagram Gantt-nya.
  4. Periksa span invoke_connector untuk melihat tempat proses terhenti atau gagal.
  5. Selain itu, Anda dapat menemukan token bantuan unik yang terkait dengan permintaan tertentu. Jika Anda perlu mengeskalasikan masalah yang kompleks ke Dukungan Google Cloud , bagikan token bantuan ini untuk mempercepat penyelidikan.

Melihat payload error

  1. Klik span yang gagal di Trace Explorer.
  2. Di panel detail, klik Show logs.
  3. Tindakan ini akan otomatis mengarahkan Anda ke Cloud Logging, yang difilter ke permintaan yang tepat. Di sini, Anda dapat membaca payload log mentah untuk mengidentifikasi signature error yang tepat (seperti RESOURCE_EXHAUSTED atau PERMISSION_DENIED).

Melakukan referensi silang log audit penggunaan

Jika payload log menunjukkan masalah IAM, cakupan yang tidak ada, atau penolakan izin, lakukan referensi silang Cloud Audit Logs Anda:

  1. Di konsol Google Cloud , buka halaman Logs Explorer.

    Buka Logs Explorer

  2. Tinjau histori administratif. Verifikasi apakah administrator Anda baru-baru ini mengubah filter tindakan atau mencabut izin yang diperlukan.

Contoh: Melacak permintaan penyimpanan data yang gagal

Bayangkan seorang pengguna meminta agen Gemini Enterprise Anda untuk mendapatkan status masalah Jira, tetapi agen tersebut menampilkan pesan kegagalan umum. Berikut cara menggunakan alur kerja kemampuan observasi untuk menemukan akar masalah:

  1. Periksa tren error: Sebelum mencari error satu per satu, Anda perlu mengetahui seberapa luas masalahnya. Buka Metrics Explorer di Cloud Monitoring dan filter metrik permintaan penyimpanan data Anda berdasarkan tool_id: get_issue. Anda mungkin melihat lonjakan error RESOURCE_EXHAUSTED yang besar dan tiba-tiba. Hal ini mengonfirmasi bahwa masalahnya bersifat sistemik, bukan sekadar kesalahan ketik yang dilakukan pengguna satu kali.
  2. Temukan permintaan yang gagal: Buka Trace Explorer dan tetapkan filter waktu ke satu jam terakhir. Dalam diagram sebar, Anda akan melihat sekelompok trace dengan ikon error merah yang menunjukkan kegagalan. Klik salah satu rekaman aktivitas terbaru ini untuk menyelidiki.
  3. Periksa diagram Gantt: Diagram Gantt memvisualisasikan perjalanan permintaan. Anda melihat span induk yang berhasil untuk pemilihan rute agen awal, tetapi di bawahnya terdapat span invoke_connector yang gagal dan secara khusus menargetkan penyimpanan data Jira Cloud.
  4. Beralih ke log: Klik span invoke_connector yang gagal. Di panel Trace details, klik Show logs.

  5. Mengidentifikasi akar masalah: Logs Explorer akan terbuka, yang telah difilter sebelumnya ke ID trace yang tepat. Sekarang Anda dapat memeriksa payload log yang dihasilkan oleh penyimpanan data untuk mengidentifikasi error yang tepat:

    
"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\":{}}"

    Dalam pesan error payload ini, Anda dapat melihat alat tertentu (get_issue) yang gagal dan pesan eksplisit yang menunjukkan bahwa pengguna yang menjalankan permintaan tidak memiliki akses ke resource tertentu dalam sistem target.

  6. Penyelesaian: Dengan menggunakan bagian Error umum, Anda dapat mengidentifikasi error ini sebagai error Akses resource pengguna akhir tidak ada. Agen Gemini Enterprise berhasil terhubung ke Jira Cloud, tetapi Jira Cloud menolak kueri karena pengguna tidak memiliki izin. Untuk mengatasi masalah ini, minta administrator Jira Cloud Anda untuk memberi pengguna akses ke resource tertentu.

Error yang biasa terjadi

Saat meninjau payload error di Cloud Logging, fokuslah pada signature error yang luas. Sebagian besar error penyimpanan data dapat diselesaikan sendiri sepenuhnya. Temukan error yang Anda alami dalam daftar berikut untuk menentukan akar masalah dan perbaikannya.

Error autentikasi & akses

Error ini terjadi jika ada masalah pada kredensial, cakupan, atau kebijakan administratif yang mencegah akses ke resource yang diperlukan. Jika Anda mengalami error ini, Cloud Audit Logs berguna untuk men-debug perubahan IAM terbaru, update filter tindakan, atau izin yang dicabut.

Token OAuth sudah tidak berlaku atau tidak valid

  • Signature Error: HTTP request failed with status code 401 / 401 Unauthorized
  • Penyebab Utama: Token OAuth telah habis masa berlakunya atau tidak valid.
  • Penyelesaian: Berikan otorisasi ulang penyimpanan data di setelan Gemini Enterprise Anda untuk membuat token baru.

Alat diblokir oleh filter tindakan

  • Signature Error: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • Penyebab Utama: Administrator telah memblokir alat menggunakan filter tindakan.
  • Penyelesaian: Administrator harus memperbarui daftar tindakan atau alat yang diizinkan.

Cakupan OAuth tidak ada

  • Signature Error: Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted ATAU Cause: Insufficient Permission
  • Penyebab Utama: Pendaftaran aplikasi di platform pihak ketiga tidak memiliki cakupan yang diperlukan.
  • Penyelesaian: Administrator harus memberikan cakupan yang sama persis dengan yang disebutkan dalam log dan memberikan otorisasi ulang pada aplikasi.

Izin project IAM tidak ada

  • Signature Error: Access Denied: User does not have [permission] / mcp.tools.call permission
  • Penyebab Utama: Pemanggil atau akun layanan tidak memiliki izin IAM Google Cloud yang diperlukan dalam project target.
  • Penyelesaian: Berikan izin IAM yang disebutkan kepada pemanggil.

Error performa & throttling

Error ini dipicu saat volume permintaan melebihi batas yang ditetapkan oleh API atau layanan target. Cloud Trace membantu mengidentifikasi dengan tepat berapa lama permintaan yang dibatasi ini tertunda sebelum gagal.

Throttling 429 API pihak ketiga

  • Signature Error: Cause: Request has been rate limited
  • Penyebab Utama: Anda membuat permintaan lebih cepat daripada yang diizinkan oleh API pihak ketiga.
  • Penyelesaian: Kurangi rasio permintaan Anda, terapkan strategi backoff, atau minta penambahan kuota dari penyedia pihak ketiga.

Tombol "Aktifkan tindakan" tidak terlihat

  • Error Signature: Tombol Enable actions tidak terlihat atau dinonaktifkan di konsol setelah membuat penyimpanan data.
  • Penyebab Utama: Penyimpanan data memiliki fungsi terbatas (seperti hanya penelusuran gabungan, hanya penyerapan, atau hanya penelusuran) dan tidak mendukung tindakan.
  • Penyelesaian: Tindakan tidak dapat diaktifkan pada jenis penyimpanan data ini.

Error visibilitas dan resource

Error ini menunjukkan bahwa meskipun autentikasi mungkin berhasil, pengguna atau aplikasi tidak memiliki hak khusus untuk melihat atau berinteraksi dengan data yang diminta.

Pembatasan visibilitas pihak ketiga

  • Signature Error: 422 ... you do not have permission to view [Resource/Users]
  • Akar Masalah: Pembatasan visibilitas atau kebijakan organisasi di platform pihak ketiga mencegah pengambilan data.
  • Penyelesaian: Sesuaikan keanggotaan organisasi pihak ketiga Anda, atau kurangi batas cakupan kueri Anda.

Tidak ada akses resource pengguna akhir

  • Signature Error: permission denied: [user] does not have access to [Resource]
  • Penyebab Utama: Pengguna akhir yang menjalankan permintaan tidak memiliki akses ke komponen atau resource tertentu dalam sistem target.
  • Penyelesaian: Berikan akses kepada pengguna ke resource secara langsung dalam sistem target.

Error sistem dan sisi server

Error ini disebabkan oleh masalah infrastruktur, waktu tunggu habis, atau kesalahan konfigurasi backend dan biasanya tidak dapat diselesaikan sendiri.

Endpoint pihak ketiga yang lambat atau kelebihan beban

  • Signature Error: context deadline exceeded
  • Penyebab Utama: Endpoint pihak ketiga lambat atau kelebihan beban, sehingga menyebabkan waktu tunggu permintaan di sisi Google habis.
  • Penyelesaian: Coba lagi permintaan tersebut. Jika error terus berlanjut, hubungi Google Cloud Dukungan untuk penyesuaian waktu tunggu.

Kesalahan konfigurasi binding kredensial server MCP

  • Signature Error: CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • Penyebab Utama: Ada masalah kebijakan sisi server yang menyebabkan binding kredensial server MCP salah dikonfigurasi. This is not customer-actionable.
  • Penyelesaian: Hubungi Dukungan Google Cloud .

Mendapatkan dukungan

Jika Anda mengalami error context deadline exceeded atau CredsPermissionException yang terus-menerus, Anda mungkin perlu mengajukan tiket dukungan ke Dukungan Google Cloud .

Untuk mempercepat penyelesaian, kumpulkan artefak berikut dari alat kemampuan observasi Anda sebelum membuka tiket:

  • Dari Cloud Logging: Payload log JSON lengkap dari error.
  • Dari Cloud Trace: Token bantuan dan detail span tertentu (termasuk ID trace) yang terkait dengan permintaan yang gagal.
  • Dari Log Audit Penggunaan: Stempel waktu modifikasi IAM atau perubahan kebijakan yang relevan yang mungkin telah memicu masalah.