이 페이지를 사용하여 Gemini Enterprise 데이터 스토어 관련 문제를 진단하고 해결하세요. 데이터 스토어에서 정보를 가져오지 못하는 경우 일관된 단계별 모니터링 가능성 여정을 통해 문제를 독립적으로 디버깅할 수 있습니다.
오류를 전체적으로 파악하려면 Google Cloud의 모니터링 가능성 도구가 어떻게 함께 작동하는지 이해해야 합니다.
- Cloud Monitoring: 문제가 발생한 시점을 감지합니다. 이를 사용하여 상위 수준 추세, 오류율을 확인하고 데이터 스토어에 대한 알림을 설정할 수 있습니다.
- Cloud Trace: 문제가 발생하는 위치를 찾습니다. 이를 사용하여 요청의 수명 주기를 확인하고, 스팬을 분석하고, 지연 시간 또는 실패를 유발한 단계를 정확하게 식별할 수 있습니다.
- Cloud Logging: 문제가 발생하는 이유를 설명합니다. 실패한 요청과 관련된 정확한 오류 메시지와 페이로드를 읽는 데 사용합니다.
- Cloud 감사 로그: 작업을 차단한 사용자 또는 정책을 식별합니다. 이를 사용하여 보안 규정 준수, 권한 변경, 액세스 거부를 유발할 수 있는 관리 작업을 추적할 수 있습니다.
디버깅 워크플로
데이터 스토어 문제를 조사할 때는 다음 순차적 워크플로를 따라 근본 원인을 격리하고 해결하세요.
오류율 추세 확인
Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.
대시보드를 확인하고 데이터 스토어 요청 수를 검토한 후 도구 ID 및 엔진 ID로 필터링합니다. 문제가 일회성 오류인지 아니면 즉각적인 조치가 필요한 광범위한 시스템 급증인지 확인할 수 있습니다.
실패한 특정 요청 찾기
-
Google Cloud 콘솔에서
Trace 탐색기 페이지로 이동합니다.검색창을 사용하여 이 페이지를 찾을 수도 있습니다.
- 분산형 차트에서 오류 아이콘 (빨간색 느낌표)이 있거나 지연 시간이 비정상적으로 높은 trace를 찾습니다.
- trace를 클릭하여 Gantt 차트를 확인합니다.
invoke_connector스팬을 확인하여 프로세스가 중단되거나 실패한 위치를 확인합니다.- 또한 특정 요청과 연결된 고유한 지원 토큰을 찾을 수 있습니다. 복잡한 문제를 Google Cloud 지원팀에 에스컬레이션해야 하는 경우 이 지원 토큰을 공유하여 조사를 신속하게 진행하세요.
오류 페이로드 보기
- Trace 탐색기에서 실패한 스팬을 클릭합니다.
- 세부정보 창에서 로그 표시를 클릭합니다.
- 그러면 Cloud Logging으로 자동 전환되어 해당 요청으로 필터링됩니다. 여기에서 원시 로그 페이로드를 읽어 정확한 오류 서명 (예:
RESOURCE_EXHAUSTED또는PERMISSION_DENIED)을 식별할 수 있습니다.
교차 참조 사용 감사 로그
로그 페이로드에 IAM 문제, 누락된 범위 또는 권한 거부가 표시되면 Cloud 감사 로그를 교차 참조합니다.
Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
관리 기록을 검토합니다. 관리자가 최근에 작업 필터를 수정했거나 필요한 권한을 취소했는지 확인합니다.
예시: 실패한 데이터 스토어 요청 추적
사용자가 Gemini Enterprise 에이전트에게 Jira 문제의 상태를 가져오라는 프롬프트를 입력했는데 에이전트가 일반적인 실패 메시지를 반환한다고 가정해 보겠습니다. 모니터링 가능성 워크플로를 사용하여 근본 원인을 찾는 방법은 다음과 같습니다.
- 오류 추세 확인: 개별 오류를 찾기 전에 문제가 얼마나 광범위한지 파악해야 합니다. Cloud Monitoring에서 측정항목 탐색기를 열고
tool_id: get_issue로 데이터 스토어 요청 측정항목을 필터링합니다.RESOURCE_EXHAUSTED오류가 갑자기 급증할 수 있습니다. 이는 일회성 사용자 오타가 아니라 시스템 문제임을 확인해 줍니다. - 실패한 요청 찾기: Trace 탐색기를 열고 시간 필터를 지난 1시간으로 설정합니다. 분산형 차트에서 실패를 나타내는 빨간색 오류 아이콘이 있는 trace 클러스터가 표시됩니다. 최근 trace 중 하나를 클릭하여 조사합니다.
- Gantt 차트 검토: Gantt 차트는 요청의 여정을 시각화합니다. 초기 에이전트 라우팅에 대한 성공적인 상위 스팬이 표시되지만, 그 아래에 Jira Cloud 데이터 스토어를 구체적으로 타겟팅하는 실패한
invoke_connector스팬이 중첩되어 있습니다. - 로그로 전환: 실패한
invoke_connector스팬을 클릭합니다. Trace 세부정보 창에서 로그 표시를 클릭합니다. 근본 원인 파악: 로그 탐색기가 열리고 정확한 trace 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 감사 로그를 사용하여 최근 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: 실패한 요청과 연결된 지원 토큰 및 특정 스팬 세부정보 (trace ID 포함)
- 사용 감사 로그: 문제를 일으켰을 수 있는 관련 IAM 수정 타임스탬프 또는 정책 변경사항입니다.