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 secara independen dengan mengikuti perjalanan kemampuan observasi yang kohesif dan langkah demi langkah.

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

  • Cloud Monitoring: Mendeteksi kapan terjadi masalah. Gunakan fitur ini untuk melihat tren tingkat tinggi, rasio error, dan menyiapkan pemberitahuan untuk penyimpanan data Anda.
  • Cloud Trace: Menemukan tempat terjadinya masalah. Gunakan fitur 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 halaman 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 dapat 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 spesifik yang gagal
  3. Melihat payload error
  4. 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 serta filter menurut ID Alat dan ID Mesin Telusur. Anda dapat menentukan apakah masalah tersebut merupakan error satu kali atau lonjakan sistemik yang meluas dan memerlukan perhatian segera.

Menemukan permintaan spesifik 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 rentang invoke_connector untuk melihat di mana 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 Google Cloud Dukungan, bagikan token bantuan ini untuk mempercepat penyelidikan.

Melihat payload error

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

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 pengguna meminta agen Gemini Enterprise Anda untuk mendapatkan status masalah Jira, tetapi agen 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 besar dan tiba-tiba pada error RESOURCE_EXHAUSTED. Hal ini mengonfirmasi bahwa masalahnya bersifat sistemik, bukan hanya kesalahan ketik pengguna satu kali.
  2. Temukan permintaan yang gagal: Buka Trace Explorer dan tetapkan filter waktu ke satu jam terakhir. Dalam diagram sebar, Anda melihat sekelompok rekaman aktivitas 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. Pivot ke log: Klik rentang invoke_connector yang gagal. Di panel Detail rekaman aktivitas, klik Tampilkan log.

  5. Identifikasi penyebab utama: Logs Explorer akan terbuka, yang telah difilter sebelumnya ke ID rekaman aktivitas 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 mengatasinya, 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 penyebab utama 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, pembaruan filter tindakan, atau izin yang dicabut.

Token OAuth sudah tidak berlaku atau tidak valid

  • Tanda Tangan Error: HTTP request failed with status code 401 / 401 Unauthorized
  • Penyebab Utama: Token OAuth telah habis masa berlakunya atau tidak valid.
  • Penyelesaian: Berikan ulang otorisasi 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 persis yang disebutkan dalam log dan mengizinkan ulang 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 bernama kepada pemanggil.

Error performa & throttling

Error ini dipicu saat volume permintaan melebihi batas yang ditetapkan oleh API atau layanan target. Cloud Trace membantu mengidentifikasi secara 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 peningkatan kuota dari provider pihak ketiga.

Tombol "Aktifkan tindakan" tidak terlihat

  • Tanda Tangan Error: Tombol Aktifkan tindakan 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

  • Tanda Tangan 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

  • Tanda Tangan 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: Beri pengguna akses 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

  • Tanda Tangan Error: CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • Penyebab: Ada masalah kebijakan sisi server yang menyebabkan pengikatan kredensial server MCP salah dikonfigurasi. Hal ini tidak dapat ditindaklanjuti oleh pelanggan.
  • Penyelesaian: Hubungi Dukungan Google Cloud .

Mendapatkan dukungan

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

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

  • Dari Cloud Logging: Payload log JSON lengkap dari error.
  • Dari Cloud Trace: Token bantuan dan detail rentang 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 memicu masalah.