このページでは、Gemini Enterprise データストアに関する問題を診断して解決する方法について説明します。データストアが情報を取得できない場合は、一貫したステップごとのオブザーバビリティ ジャーニーに沿って、問題を個別にデバッグできます。
エラーの全体像を把握するには、 Google Cloudオブザーバビリティ ツールがどのように連携して動作するかを理解してください。
- Cloud Monitoring: 問題がいつ 発生したかを検出します。これを使用して、データストアの全体的な傾向とエラー率を確認し、アラートを設定します。
- Cloud Trace: 問題がどこ で発生しているかを検出します。これを使用して、リクエストのライフサイクルを表示し、スパンを分析して、レイテンシの増加や失敗の原因となったステップを正確に特定します。
- Cloud Logging: 問題がなぜ 発生しているかを説明します。これを使用して、失敗したリクエストに関連付けられた正確なエラー メッセージとペイロードを読み取ります。
- Cloud Audit Logs: アクションをブロックしたユーザー またはポリシーを特定します。これを使用して、アクセス拒否の原因となっている可能性のあるセキュリティ コンプライアンス、権限の変更、管理アクションを追跡します。
デバッグのワークフロー
データストアの問題を調査する場合は、次の順序でワークフローを実行して、根本原因を特定して解決します。
エラー率の傾向を確認する
Google Cloud コンソールで、[Metrics Explorer] ページに移動します。
ダッシュボードを確認し、データストアのリクエスト数を調べて、[ツール ID] と [エンジン ID] でフィルタします。 問題が単発のエラーなのか、早急な対応が必要な広範囲のシステム上の急増なのかを判断できます。
失敗した特定のリクエストを見つける
-
コンソールで、 Google Cloud
[Trace エクスプローラ] ページに移動します。
このページは、検索バーを使用して見つけることもできます。
- エラー アイコン（赤い感嘆符）または異常に高いレイテンシを含むトレースの散布図を確認します。
- トレースをクリックして、ガントチャートを表示します。
invoke_connectorスパンを確認して、プロセスが停止または失敗した場所を確認します。- また、特定のリクエストに関連付けられた一意のアシスト トークンを見つけることもできます。複雑な問題を Google Cloud サポートにエスカレーションする必要がある場合は、このアシスト トークンを共有して調査を迅速化してください。
エラー ペイロードを表示する
- [Trace エクスプローラ] で失敗したスパンをクリックします。
- 詳細ペインで [ログを表示] をクリックします。
- これにより、Cloud Logging に自動的にピボットされ、そのリクエストにフィルタされます。ここで、未加工のログ ペイロードを読み取って、正確なエラー シグネチャ（
RESOURCE_EXHAUSTEDやPERMISSION_DENIEDなど）を特定できます。
使用状況の監査ログを相互参照する
ログ ペイロードが IAM の問題、スコープの欠落、権限拒否を示している場合は、Cloud Audit Logs を相互参照します。
コンソール Google Cloud で、[**ログ エクスプローラ**] ページに移動します。
管理履歴を確認します。管理者が最近アクション フィルタを変更したか、必要な権限を取り消したかを確認します。
例: 失敗したデータストア リクエストをトレースする
ユーザーが Gemini Enterprise エージェントに Jira の問題のステータスを取得するようにプロンプトを表示したものの、エージェントが一般的な失敗メッセージを返したとします。オブザーバビリティ ワークフローを使用して根本原因を見つける方法は次のとおりです。
- エラーの傾向を確認する: 個々のエラーを探す前に、問題の範囲を把握する必要があります。Cloud Monitoring で [Metrics Explorer] を開き、データストアのリクエスト指標を
tool_id: get_issueでフィルタします。RESOURCE_EXHAUSTEDエラーが大幅に急増している可能性があります。これにより、単なるユーザーの入力ミスではなく、システム上の問題であることが確認できます。 - 失敗したリクエストを見つける: [Trace エクスプローラ] を開き、時間フィルタを過去 1 時間に設定します。散布図に、失敗を示す赤いエラー アイコンが付いたトレースのクラスタが表示されます。これらの最近のトレースのいずれかをクリックして調査します。
- ガントチャートを確認する: ガントチャートには、リクエストのジャーニーが視覚化されます。最初のエージェント ルーティングの親スパンは成功していますが、その下に、Jira Cloud データストアを特にターゲットとする失敗した
invoke_connectorスパンがネストされています。 - ログにピボットする: 失敗した
invoke_connectorスパンをクリックします。[トレースの詳細] ペインで [ログを表示] をクリックします。 根本原因を特定する: [ログ エクスプローラ] が開き、正確なトレース ID で事前フィルタされます。データストアによって生成されたログ ペイロードを調べて、正確なエラーを特定できます。
"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\":{}}"このペイロード エラー メッセージでは、失敗した特定のツール（
get_issue）と、リクエストを実行するユーザーがターゲット システム内の特定のリソースにアクセスできないことを示す明示的なメッセージを確認できます。解決策: 一般的なエラーのセクションを使用して、エンドユーザーのリソース アクセス権がないエラーとして特定できます。Gemini Enterprise エージェントは Jira Cloud に正常に接続しましたが、ユーザーに権限がないため、Jira Cloud がクエリを拒否しました。この問題を解決するには、Jira Cloud 管理者に、特定のリソースへのアクセス権をユーザーに付与するよう依頼してください。
一般的なエラー
Cloud Logging でエラー ペイロードを確認する場合は、広範なエラー シグネチャに注目してください。ほとんどのデータストア エラーは完全に自己解決できます。次のリストで発生したエラーを見つけて、根本原因と修正方法を特定してください。
認証とアクセスに関するエラー
これらのエラーは、必要なリソースへのアクセスを妨げる認証情報、スコープ、管理ポリシーに問題がある場合に発生します。これらのエラーが発生した場合は、Cloud Audit Logs を使用して、最近の IAM の変更、アクション フィルタの更新、取り消された権限をデバッグすると便利です。
OAuth トークンが無効または期限切れ
- エラー シグネチャ:
HTTP request failed with status code 401 / 401 Unauthorized - 根本原因: OAuth トークンが無効または期限切れです。
- 解決策: Gemini Enterprise の設定でデータストアを再承認して、新しいトークンを生成します。
アクション フィルタによってツールがブロックされている
- エラー シグネチャ:
Permission "connectors.tool.execute" denied ... rejected by admin filter configuration - 根本原因: 管理者がアクション フィルタを使用してツールをブロックしました。
- 解決策: 管理者がアクションまたはツールの許可リストを更新する必要があります。
OAuth スコープがない
- エラー シグネチャ:
Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] grantedまたはCause: Insufficient Permission - 根本原因: サードパーティ プラットフォームのアプリケーション登録に必要なスコープがありません。
- 解決策: 管理者がログに記載されている正確なスコープを付与し、アプリを再承認する必要があります。
IAM プロジェクト権限がない
- エラー シグネチャ:
Access Denied: User does not have [permission] / mcp.tools.call permission - 根本原因: 呼び出し元またはサービス アカウントに、ターゲット プロジェクトに必要な Google Cloud IAM 権限がありません。
- 解決策: 呼び出し元に指定された IAM 権限を付与します。
パフォーマンスとスロットリングのエラー
これらのエラーは、リクエスト数がターゲット API またはサービスで設定された上限を超えた場合にトリガーされます。Cloud Trace を使用すると、これらのスロットリングされたリクエストが失敗するまでにどのくらいの時間がかかるかを正確に特定できます。
サードパーティ API 429 スロットリング
- エラー シグネチャ:
Cause: Request has been rate limited - 根本原因: サードパーティ API で許可されているよりも速い速度でリクエストを行っています。
- 解決策: リクエスト レートを減らすか、バックオフ戦略を実装するか、サードパーティ プロバイダに割り当ての引き上げをリクエストします。
可視性とリソースのエラー
これらのエラーは、認証は成功しても、リクエストされたデータを表示または操作するための特定の権限がユーザーまたはアプリケーションにないことを示します。
サードパーティの可視性の制限
- エラー シグネチャ:
422 ... you do not have permission to view [Resource/Users] - 根本原因: サードパーティ プラットフォームの可視性の制限または組織のポリシーにより、データの取得が妨げられています。
- 解決策: サードパーティ組織のメンバーシップを調整するか、クエリ スコープの上限を減らします。
エンドユーザーのリソース アクセス権がない
- エラー シグネチャ:
permission denied: [user] does not have access to [Resource] - 根本原因: リクエストを実行するエンドユーザーに、ターゲット システム内の特定のコンポーネントまたはリソースへのアクセス権がありません。
- 解決策: ターゲット システム内でリソースへのアクセス権をユーザーに直接付与します。
システムとサーバーサイドのエラー
これらのエラーは、インフラストラクチャの問題、タイムアウト、バックエンドの構成ミスが原因で発生し、通常は自己解決できません。
サードパーティ エンドポイントが遅いか、過負荷になっている
- エラー シグネチャ:
context deadline exceeded - 根本原因: サードパーティ エンドポイントが遅いか、過負荷になっているため、Google 側のリクエストがタイムアウトしています。
- 解決策: リクエストを再試行してください。エラーが解決しない場合は、タイムアウトの調整について Google Cloud サポートにお問い合わせください。
MCP サーバーの認証情報バインディングの構成ミス
- エラー シグネチャ:
CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER - 根本原因: MCP サーバーの認証情報バインディングが誤って構成されているサーバーサイドのポリシーの問題があります。これはお客様が対応できるものではありません。
- 解決策: サポートに Google Cloud お問い合わせください。
サポートを受ける
context deadline exceeded エラーまたは CredsPermissionException エラーが解決しない場合は、 Google Cloud サポートにサポート チケットを提出する必要があります。
解決を迅速化するため、チケットを開く前に、オブザーバビリティ ツールから次のアーティファクトを収集してください。
- Cloud Logging から: エラーの完全な JSON ログ ペイロード。
- Cloud Trace から: 失敗したリクエストに関連付けられたアシスト トークンと特定のスパンの詳細（トレース ID を含む）。
- 使用状況の監査ログから: 問題を引き起こした可能性のある関連する IAM 変更のタイムスタンプまたはポリシーの変更。