trace 및 스팬 액세스

이 문서에서는 Gemini Enterprise 앱에서 생성된 trace 및 스팬에 액세스하고 이를 보는 방법을 설명합니다. trace 및 스팬은 어시스턴트 또는 에이전트를 사용할 때와 같이 애플리케이션 내 요청의 성능과 실행 흐름에 대한 자세한 통계를 제공합니다.

Trace 탐색기 를 사용하거나 에이전트의 trace 탭을 사용하여 개별 에이전트 내에서 직접 trace 데이터를 볼 수 있습니다.

주요 개념

이 섹션에서는 Gemini Enterprise의 관측가능성과 관련된 주요 개념을 소개합니다.

개념	설명
Trace	trace는 여러 서비스와 구성요소를 통과할 때 단일 요청 또는 트랜잭션을 나타내는 스팬 모음입니다. 예를 들어 trace는 요청의 전체 수명 주기를 나타냅니다. 여기에는 Gemini Enterprise 어시스턴트에서 질문하는 사용자, Gemini Enterprise 어시스턴트의 응답, 이메일 전송과 같이 답변에 의해 트리거되는 후속 작업이 포함됩니다.
스팬	스팬은 trace 내에서 시간 지정된 단일 작업 단위입니다. 함수 호출, API 요청, 데이터베이스 쿼리와 같은 특정 작업을 나타냅니다. 각 스팬에는 시작 및 종료 시간, 고유 ID, 다른 스팬과의 관계와 같은 세부정보가 포함됩니다. 이러한 관계가 함께 trace를 구성합니다.
스팬 로그	스팬 로그는 특정 스팬과 연결된 타임스탬프가 지정된 자유 형식 메시지 또는 이벤트입니다. 스팬 실행에 대한 자세한 컨텍스트 정보를 제공하여 사용자가 문제를 디버그하고 요청 흐름을 이해하는 데 도움이 됩니다.

시작하기 전에

다음 항목이 있는지 확인합니다.

• Gemini Enterprise 관리자 역할 또는 Google Cloud 콘솔 Gemini Enterprise 사용자 역할.

• 기존 Gemini Enterprise 웹 앱. 새 앱을 만드는 방법에 대한 자세한 내용은 앱 만들기를 참조하세요.

• trace에 액세스하려면 Cloud Trace 사용자 역할 (roles/cloudtrace.user)이 있어야 합니다.

• OpenTelemetry trace 및 로그의 계측 사용 설정 관측가능성 설정을 사용 설정합니다. 에이전트 유형에 따라 앱 수준 구성 (Core 어시스턴트 에이전트의 경우) 또는 에이전트의 구성 탭 (Agent Designer 직원 제작 에이전트 및 Deep Research 에이전트의 경우) 내에서 이 설정을 사용 설정합니다. 자세한 내용은 관측가능성 설정 관리를 참조하세요.

데이터 보관

Gemini Enterprise 앱에서 생성된 trace 및 스팬은 프로젝트의 Cloud Trace에 저장되며 보관은 Cloud Trace에서 관리합니다. Google Cloud 기본적으로 Cloud Trace는 스팬 데이터를 30일 동안 보관합니다. 보관 기간보다 오래된 데이터는 자동으로 삭제됩니다. 공식적이고 최신 보관 값은 Cloud Trace 할당량 및 한도 문서의 Cloud Trace 보관 기간을 참조하세요.

Trace 탐색기에서 trace 액세스

Trace 탐색기를 사용하여 trace 및 스팬에 액세스하려면 다음 단계를 따르세요.

1. 콘솔에서 Trace 탐색기 페이지로 이동합니다. Google Cloud

   trace 탐색기로 이동

2. Gemini Enterprise 앱이 생성된 Google Cloud 프로젝트를 선택합니다. 프로젝트의 모든 스팬이 표시됩니다.

3. 표에서 스팬 ID 를 클릭하여 스팬의 기간 및 기타 속성을 포함한 trace 세부정보를 확인합니다.

   참고: Trace 탐색기 사용에 대한 자세한 내용은 trace 찾기 및 탐색을 참조하세요.

   

trace 필터링 및 검색

프로젝트의 Trace 탐색기 내에서 다음 필터, 쿼리 매개변수, 속성을 사용하여 Gemini Enterprise 에이전트 및 데이터 커넥터 실행을 격리하고 분석할 수 있습니다.

• 패싯 필터:
  • 서비스: AssistantService 또는 connectorsexecution으로 필터링하여 플랫폼 에이전트 및 데이터 커넥터 요청 경로를 격리합니다.
  • 스팬: /AssistantService.StreamAssist로 필터링하여 루트 사용자 턴 스팬을 찾거나 execute_tool <tool_name> 및 invoke_connector <connector>와 같은 하위 스팬을 검색합니다.
• 직접 trace ID 조회: StreamAssist의 응답 헤더에서 추출할 수 있는 표준 32자 W3C trace ID를 사용하여 trace를 직접 찾습니다. x-cloud-trace-context
• 커스텀 속성: 턴 수준 기존 어시스턴트 토큰을 W3C trace 폭포에 매핑하려면 execute_tool 또는 invoke_connector 스팬에서 gemini_enterprise.assist_token 속성으로 쿼리합니다.
• 리소스 속성: 내보낸 모든 스팬은 cloud.region
• 리소스 속성: 내보낸 모든 스팬은 cloud.region 속성을 전달합니다. 이 속성은 요청을 처리한 Gemini Enterprise 제공 위치(예: global, us, eu)를 나타냅니다. 이 속성으로 필터링하여 리전 간 성능을 비교할 수 있습니다. 이 비교는 데이터 커넥터가 한 위치에서는 성공하지만 다른 위치에서는 실패하는 경우에 유용합니다. 이 값은 서드 파티 데이터 소스를 호스팅하는 리전이 아니라 앱을 제공하는 위치를 나타냅니다. 이 필터를 적용하려면 스팬 필터 적용을 참조하세요.

에이전트의 trace 액세스

스팬 trace 레코드 및 상위-하위 실행 구조의 자세한 시간순 요약을 표시하는 에이전트의 trace 탭에서 개별 에이전트의 trace 스팬을 직접 볼 수도 있습니다.

참고: trace 탭은 Core 어시스턴트 에이전트, Agent Designer 직원 제작 에이전트, Deep Research 에이전트에서 사용할 수 있습니다.

에이전트의 trace에 액세스하려면 다음 단계를 따르세요.

1. 콘솔에서 앱으로 이동한 후 에이전트를 클릭합니다. Google Cloud
2. 검사할 에이전트를 선택한 후 trace 탭을 클릭합니다.

trace 요약 표

trace 탭의 기본 표에는 각 trace 스팬에 대한 다음 정보가 표시됩니다.

• 상태: trace의 현재 상태입니다 (현재 설정되지 않음이 표시됨).
• trace 스팬 ID: trace 스팬의 고유 식별자입니다. 스팬 ID 링크를 클릭하여 세부정보를 드릴다운합니다.
• 스팬 이름: 스팬이 수행하는 작업에 대한 간략한 설명입니다. Gemini Enterprise 데이터 커넥터의 스팬 예시는 다음과 같습니다.
  • execute_tool <tool_name>: 에이전트 런타임의 도구 디스패치 레이어 중에 내보내집니다 (예: execute_tool federated_search).
  • invoke_connector <connector>: 커넥터 실행 레이어에서 생성되어 특정 커넥터에 대한 요청 로직을 나타냅니다 (예: invoke_connector jira 또는 invoke_connector servicenow). 기본 서비스 측 RPC 스팬을 대체합니다.
• 스팬 유형: 스팬 유형입니다. 옵션은 다음과 같습니다.
  • Agent to Tool: 에이전트에서 외부 도구로의 호출입니다 (execute_tool 및 invoke_connector 작업에 재사용됨).
  • Invoke Agent: 에이전트의 호출입니다.
  • Agent to Model: 에이전트에서 대규모 언어 모델로의 요청입니다.
• 기간: trace 스팬을 완료하는 데 걸린 시간 (분)입니다.
• 입력: 스팬으로 전송된 입력 데이터 또는 메시지(있는 경우)입니다.
• 출력: 스팬에서 반환된 출력 결과(있는 경우)입니다.
• 시작 시간: 스팬 실행이 시작된 정확한 타임스탬프입니다.

자세한 trace 보기

trace 스팬 ID 를 클릭하면 다음이 포함된 세부정보 페이지가 열립니다.

1. 요약: 시작 시간, 기간, 총 스팬 수와 같은 기준 메타데이터를 봅니다. Cloud Trace에서 보기 를 클릭하거나 그래프 와 타임라인 보기 버튼 간에 전환할 수 있습니다.
2. 시각화: 모든 trace 스팬의 상위-하위 관계를 보여주는 그래픽 계층 구조 또는 타임라인 뷰 간에 전환합니다.
3. 선택한 스팬 세부정보: 단일 스팬을 선택하여 다음을 포함할 수 있는 세부 섹션을 표시합니다.
   • 요약: 스팬 이름, 대상 서비스, 이 작업이 있는 총 스팬 수, 총 기간 (초)을 표시합니다.
   • 로그: 구성된 경우 관련 이벤트 세부정보를 봅니다. 로그 보기 를 클릭하여 표준 로그로 직접 이동합니다.
   • 평가: 구성된 경우 평가 결과를 표시합니다.
   • 입력 및 출력: 전체 요청 및 응답 페이로드입니다.
   • 로그 및 이벤트: 이 스팬 실행 중에 발생한 이벤트 목록입니다.
   • 스택 trace: 스팬 실행이 실패한 경우의 오류 세부정보입니다.
   • 메타데이터 및 링크: 관련 클라우드 탐색기 항목을 참조하는 링크입니다.
   • 속성: 리소스 태그 및 추가 키-값 관측가능성 매개변수입니다.

상위-하위 스팬 계층 구조

데이터 커넥터 실행의 경우 단일 W3C trace 내의 상위-하위 스팬 중첩은 지연 시간 또는 오류가 발생하는 위치를 정확히 파악하는 데 도움이 됩니다.

1. /AssistantService.StreamAssist: 요청을 시작하는 루트 C++ 플랫폼 스팬입니다.
2. invoke_agent core_assistant: 에이전트 실행 스팬입니다.
3. execute_tool <tool_name>: 활성 도구 실행 스팬입니다 (예: execute_tool federated_search).
4. invoke_connector <connector_name> (예: invoke_connector jira 또는 invoke_connector servicenow): 서드 파티 엔드포인트에 대한 요청 수명 주기를 나타내는 커넥터 실행 스팬입니다.

생성형 AI의 실험적 시맨틱 규칙 원격 분석

경고: 이 섹션에 설명된 생성형 AI 시맨틱 규칙 원격 분석은 실험 단계에 있습니다. 속성, 스키마, 형식은 향후 버전에서 변경될 수 있습니다.

안정적인 원격 분석 외에도 Gemini Enterprise trace 스팬에는 OpenTelemetry 생성형 AI 시맨틱 규칙을 기반으로 하는 더 풍부한 메타데이터가 포함됩니다. OpenTelemetry는 이러한 규칙을 개발 상태로 분류합니다. 이 상태는 변경되거나 삭제될 수 있으며 프로덕션에서 사용해서는 안 되는 초기 단계 사양에 적용됩니다. 이러한 규칙은 아직 안정적이지 않으므로 이 Gemini Enterprise 원격 분석은 실험 단계에 있습니다. 이러한 스팬에는 에이전트 및 도구 실행, 프롬프트 및 응답 단계와 같은 에이전트, 모델, 도구 활동을 설명하는 gen_ai.* 속성이 포함됩니다.

trace 스팬의 프롬프트 및 응답 콘텐츠 (예: 프롬프트 텍스트 및 생성된 답변)는 관측가능성 설정에서 프롬프트 입력 및 응답 출력을 로깅할 수 있는 경우에만 표시됩니다. 그렇지 않으면 콘텐츠가 수정되거나 생략됩니다. 이러한 설정을 변경하려면 관측가능성 설정 관리를 참조하세요.