Memecahkan masalah penyimpanan data Gemini Enterprise

Gunakan halaman ini untuk mendiagnosis dan menyelesaikan masalah terkait penyimpanan data Gemini Enterprise. Jika penyimpanan data gagal mengambil informasi, Anda dapat men-debug masalah secara independen dengan mengikuti perjalanan observabilitas yang kohesif dan bertahap.

Untuk mendapatkan gambaran lengkap tentang error, pahami cara kerja alat observabilitas Google Cloud:

  • Cloud Monitoring: Mendeteksi kapan masalah terjadi. Gunakan alat 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 rentang, dan mengidentifikasi langkah mana yang menyebabkan latensi tinggi atau kegagalan.
  • Cloud Logging: Menjelaskan mengapa masalah terjadi. Gunakan alat ini untuk membaca pesan error dan payload yang terkait dengan 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 penyebabnya:

  1. Memeriksa tren rasio error
  2. Menemukan permintaan spesifik yang gagal
  3. Melihat payload error
  4. Audit log penggunaan referensi silang

  1. Di Google Cloud konsol, 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 adalah error satu kali atau lonjakan sistemik yang luas dan memerlukan perhatian segera.

Menemukan permintaan spesifik yang gagal

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

    Buka Trace explorer

    Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

  2. Periksa diagram pencar untuk rekaman aktivitas 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 tempat proses terhenti atau gagal.
  5. Selain itu, Anda dapat menemukan token bantuan unik yang terkait dengan permintaan tertentu. Jika Anda perlu meningkatkan 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 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 tanda tangan error yang tepat (seperti RESOURCE_EXHAUSTED atau PERMISSION_DENIED).

Membandingkan silang log audit penggunaan

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

  1. Di Google Cloud konsol, 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 observabilitas untuk menemukan akar penyebabnya:

  1. Memeriksa tren error: Sebelum mencari error individual, Anda perlu mengetahui seberapa luas masalah tersebut. Buka Metrics Explorer di Cloud Monitoring dan filter metrik permintaan penyimpanan data Anda menurut tool_id: get_issue. Anda mungkin melihat lonjakan besar dan tiba-tiba pada error RESOURCE_EXHAUSTED. Hal ini mengonfirmasi bahwa masalah tersebut adalah masalah sistemik, bukan hanya kesalahan ketik pengguna satu kali.
  2. Menemukan permintaan yang gagal: Buka Trace Explorer dan tetapkan filter waktu ke satu jam terakhir. Dalam diagram pencar, Anda akan melihat cluster rekaman aktivitas dengan ikon error merah yang menunjukkan kegagalan. Klik salah satu rekaman aktivitas terbaru ini untuk menyelidikinya.
  3. Memeriksa diagram Gantt: Diagram Gantt memvisualisasikan perjalanan permintaan. Anda akan melihat rentang induk yang berhasil untuk perutean agen awal, tetapi di bawahnya terdapat rentang invoke_connector yang gagal dan secara khusus menargetkan penyimpanan data Jira Cloud.
  4. Mengalihkan ke log: Klik rentang invoke_connector yang gagal. Di panel detail Trace, klik Show logs.

  5. Mengidentifikasi akar penyebab: 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. Menyelesaikan: 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 memberikan akses pengguna ke resource tertentu.

Error umum

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

Error autentikasi &akses

Error ini terjadi jika ada masalah dengan 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 yang tidak berlaku atau tidak valid

  • Tanda Tangan Error: HTTP request failed with status code 401 / 401 Unauthorized
  • Akar Penyebab: Token OAuth telah tidak berlaku atau tidak valid.
  • Penyelesaian: Beri otorisasi ulang penyimpanan data di setelan Gemini Enterprise Anda untuk membuat token baru.

Alat diblokir oleh filter tindakan

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

Cakupan OAuth tidak ada

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

Izin project IAM tidak ada

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

Error performa &pembatasan

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

Pembatasan API pihak ketiga 429

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

Error visibilitas dan resource

Error ini menunjukkan bahwa meskipun autentikasi mungkin berhasil, pengguna atau aplikasi tidak memiliki hak tertentu 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 Penyebab: 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.

Akses resource pengguna akhir tidak ada

  • Tanda Tangan Error: permission denied: [user] does not have access to [Resource]
  • Akar Penyebab: Pengguna akhir yang menjalankan permintaan tidak memiliki akses ke komponen atau resource tertentu dalam sistem target.
  • Penyelesaian: Berikan akses pengguna ke resource 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

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

Kesalahan konfigurasi binding kredensial server MCP

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

Mendapatkan dukungan

Jika Anda mengalami error context deadline exceeded atau CredsPermissionException yang 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 rekaman aktivitas) yang terkait dengan permintaan yang gagal.
  • Dari Log Audit Penggunaan: Stempel waktu modifikasi IAM atau perubahan kebijakan yang relevan yang mungkin memicu masalah.