trace 및 스팬 액세스

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

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

주요 개념

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

개념 설명
Trace 트레이스는 여러 서비스와 구성요소를 통과하는 단일 요청 또는 트랜잭션을 나타내는 스팬의 모음입니다.

예를 들어 트레이스는 요청의 전체 수명 주기를 나타냅니다. 여기에는 사용자가 Gemini Enterprise 어시스턴트에게 질문하는 경우, Gemini Enterprise 어시스턴트가 대답하는 경우, 대답으로 인해 트리거되는 후속 작업(예: 이메일 전송)이 포함됩니다.
스팬 스팬은 트레이스 내의 단일 시간 단위 작업입니다. 함수 호출, API 요청, 데이터베이스 쿼리와 같은 특정 작업을 나타냅니다. 각 스팬에는 시작 및 종료 시간, 고유 ID, 다른 스팬과의 관계와 같은 세부정보가 포함됩니다. 이러한 관계가 함께 트레이스를 형성합니다.
스팬 로그 스팬 로그는 특정 스팬과 연결된 타임스탬프가 지정된 자유 형식 메시지 또는 이벤트입니다. 스팬의 실행에 관한 자세한 컨텍스트 정보를 제공하여 사용자가 문제를 디버깅하고 요청 흐름을 이해할 수 있도록 지원합니다.

시작하기 전에

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

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

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

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

  • Gemini Enterprise 앱 구성에서 OpenTelemetry 추적 및 로그의 계측 사용 설정 관측 가능성 설정을 사용 설정합니다. 자세한 내용은 관측 가능성 설정 관리를 참고하세요.

Trace 탐색기에서 트레이스 액세스

추적 탐색기를 사용하여 트레이스와 스팬에 액세스하려면 다음 단계를 따르세요.

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

    trace 탐색기로 이동

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

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

    Google Cloud 콘솔의 Trace Explorer 스크린샷으로, 스팬 ID, 추적 ID, 시작 시간, 기간, 서비스 열이 있는 스팬 목록이 표시되어 있습니다.

에이전트의 trace 액세스

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

에이전트의 트레이스에 액세스하려면 다음 안내를 따르세요.

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

트레이스 요약 표

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

  • 상태: 추적의 현재 상태입니다 (현재 설정되지 않음으로 표시됨).
  • 추적 스팬 ID: 추적 스팬의 고유 식별자입니다. 스팬 ID 링크를 클릭하여 세부정보를 드릴다운합니다.
  • 스팬 이름: 스팬이 수행하는 작업에 대한 간단한 설명입니다.
  • 스팬 유형: 스팬의 유형입니다. 옵션은 다음과 같습니다.
    • Agent to Tool: 에이전트가 외부 도구를 호출합니다.
    • Invoke Agent: 에이전트 호출입니다.
    • Agent to Model: 에이전트가 대규모 언어 모델에 보내는 요청입니다.
  • 기간: 추적 스팬을 완료하는 데 걸린 시간 (분)입니다.
  • 입력: 스팬으로 전송된 입력 데이터 또는 메시지(있는 경우)
  • 출력: 스팬에서 반환된 출력 결과(있는 경우)
  • 시작 시간: 스팬이 실행되기 시작한 정확한 타임스탬프입니다.

자세한 트레이스 보기

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

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

Google Cloud 콘솔의 트레이스 탭 스크린샷으로, 스팬 타임라인과 스팬 요약이 표시되어 있습니다.