이 페이지를 사용하여 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 수정 타임스탬프 또는 정책 변경사항입니다.