trace 데이터의 집계 표현을 보거나 개별 trace 또는 특정 라벨이 포함된 trace를 찾아보려면 Trace 탐색기 페이지를 사용하세요.
다음 스크린샷은 추적 데이터가 표시되는 방식을 보여줍니다.
이 기능은 Google Cloud 프로젝트에서만 지원됩니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 관리 프로젝트를 선택합니다.
Trace 탐색기 페이지 정보
추적 데이터의 추세와 패턴을 파악할 수 있도록 지연 시간 데이터가 집계되어 차트에 표시됩니다. 히트맵은 색상을 사용하여 셀의 범위 수를 나타냅니다. 스팬이 많은 셀은 스팬이 적은 셀보다 색상이 더 어둡습니다. 각 셀의 도움말에는 지연 시간과 기타 정보가 표시됩니다. 지연 시간 백분위수 및 스팬 비율 정보도 확인할 수 있습니다.
문제를 조사할 때 특정 트레이스 또는 특정 속성이 있는 스팬만 확인해야 할 수 있습니다.
표시할 스팬을 제한하려면 필터를 적용하세요. 예를 들어 서비스, 애플리케이션, 오류 상태, 기타 속성으로 필터링할 수 있습니다.
특정 trace를 표시하려면 툴바의 페이지 조회 trace 검색 옵션을 클릭합니다.
이상치를 식별하고 개별 스팬의 세부정보를 보려면 표 형식 섹션을 사용하세요.
기간 헤더를 기준으로 스팬 및 그룹화됨 탭의 행을 정렬할 수 있습니다.
여러 서비스에서 생성되는 스팬 수를 확인하려면 그룹화됨 탭을 사용하세요. 각 행은 서비스 및 스팬 이름에 해당하며 각 항목에 지연 시간 통계가 표시됩니다.
스팬 또는 그룹화의 세부정보를 살펴보려면 표 섹션의 행에서 항목을 선택합니다. 트레이스 컨텍스트에서 스팬을 표시하는 플라이아웃이 열립니다. 이 뷰에서 스팬과 속성을 탐색하고 이벤트와 로그 데이터를 볼 수 있습니다. 추적에서 스팬과 속성을 검색하여 키워드를 찾을 수도 있습니다.
Trace 탐색기 페이지에서 사용하는 trace 데이터는 다음에 따라 달라집니다.
- 추적 데이터를 검색한 프로젝트입니다. 기본적으로 시스템은 프로젝트 선택기로 선택한 프로젝트에서만 추적 데이터를 검색합니다. 하지만 trace 범위의 프로젝트 목록을 검색하도록 페이지를 구성할 수 있습니다.
- 검색된 프로젝트에 대한 Identity and Access Management (IAM) 권한 프로젝트의 추적 데이터를 볼 권한이 없으면 Google Cloud 콘솔에 경고 메시지가 표시되고 해당 프로젝트의 데이터는 표시되지 않습니다.
- 기간 설정
- 적용하는 필터
이 페이지의 나머지 부분에서는 트레이스 데이터를 찾고 탐색하는 방법을 자세히 설명합니다.
시작하기 전에
Google Cloud 콘솔을 사용하여 trace 데이터를 보고 trace 범위를 선택하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Cloud Trace 사용자 (roles/cloudtrace.user) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 Google Cloud 콘솔을 사용하여 트레이스 데이터를 보고 트레이스 범위를 선택하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
Google Cloud 콘솔을 사용하여 트레이스 데이터를 보고 트레이스 범위를 선택하려면 다음 권한이 필요합니다.
-
추적 범위를 선택하려면 다음을 실행하세요.
cloudtrace.traceScopes.[get, list] -
기본 추적 범위를 읽으려면 다음을 실행하세요.
observability.scopes.get
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
역할에 대한 자세한 내용은 Identity and Access Management로 액세스 제어를 참조하세요.
집계된 trace 데이터 보기
trace 데이터에 대한 집계 정보를 보려면 다음 단계를 따르세요.
-
Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.
검색창을 사용하여 이 페이지를 찾을 수도 있습니다.
첫 번째 추적 데이터가 Google Cloud 프로젝트에 기록된 후 해당 데이터를 볼 수 있게 되기까지 몇 분 정도 걸릴 수 있습니다. 몇 분 후에도 trace 데이터가 표시되지 않으면 프로젝트에 표시할 데이터가 없거나 구성 문제가 있을 수 있습니다. 이 문제를 해결하는 방법은 문제 해결: Trace 인터페이스에 데이터가 없음을 참고하세요.
Trace 탐색기 페이지를 구성합니다.
- Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 관리 프로젝트를 선택합니다.
선택사항: 범위 요소를 사용하여 추적 데이터를 검색할 프로젝트를 구성합니다.
프로젝트에 저장된 추적 데이터를 표시하려면 범위 요소의 첫 번째 메뉴를
프로젝트 또는 
_Default로 설정합니다.
이 두 설정은 동일합니다.여러 프로젝트에 저장된 추적 데이터를 표시하려면 범위 요소의 첫 번째 메뉴를 펼치고 추적 범위를 선택한 다음 해당 프로젝트를 나열하는 추적 범위를 선택합니다. 선택하면 범위 메뉴에 추적 범위 아이콘(
)과 선택한 추적 범위의 이름이 표시됩니다.
반환되는 데이터는 검색된 프로젝트의 IAM 역할에 따라 다릅니다. 예를 들어 검색된 프로젝트에 액세스할 수 없는 Google Cloud 프로젝트가 포함된 경우 해당 프로젝트의 추적 데이터는 반환되지 않습니다.
자세한 내용은 trace 범위 만들기 및 관리를 참조하세요.
선택사항: 기간 선택기를 사용하거나 포인터를 사용하여 x축에서 범위를 강조 표시하여 기간을 업데이트합니다.
예를 들어 지연 시간 데이터에 추세가 있는지 확인하려면 이 선택기를 지난 2주로 설정할 수 있습니다. 스팬 데이터는 30일 동안 저장됩니다.
히트맵을 탐색합니다.
색상을 사용하여 추세와 이상치를 식별합니다. 스팬이 많은 셀은 스팬이 적은 셀보다 색상이 더 어둡습니다.
셀의 도움말을 사용하여 셀의 세부정보를 확인합니다. 툴팁에는 범위 수, 날짜 및 시간, 셀의 시간 간격이 표시됩니다.
지연 시간 백분위수와 오류율을 살펴봅니다.
지연 시간 추세를 보려면 차트 보기 메뉴를 범위 기간 (백분위수)로 설정합니다. 기간 차트에는 50번째, 90번째, 95번째, 99번째 백분위수가 표시됩니다.
시간에 따른 응답 상태를 보려면 차트 보기 메뉴를 스팬 비율로 설정합니다. 차트에는 프로젝트로 전송되는 스팬의 비율이 표시됩니다.
이상치를 찾으려면 스팬 탭을 선택하고 기간별로 표를 정렬합니다.
특정 스팬에 대한 자세한 정보를 보려면 스팬을 선택합니다. 트레이스 컨텍스트에서 스팬을 표시하는 플라이아웃이 열립니다. 그런 다음 스팬과 트레이스를 탐색할 수 있습니다.
각 서비스에 대해 생성된 스팬 수와 통계 정보를 탐색하려면 그룹화됨 탭을 선택합니다.
- 각 행은 특정 서비스 및 스팬 이름에 해당합니다.
- 기간 헤더를 기준으로 행을 정렬할 수 있습니다.
특정 그룹화에 대해 자세히 알아보려면 행의 스팬 이름을 선택합니다. 트레이스 컨텍스트에서 스팬을 표시하는 플라이아웃이 열립니다. 그런 다음 스팬과 트레이스를 살펴볼 수 있습니다.
표시할 스팬을 제한하려면 필터를 추가합니다. 트레이스 데이터 필터링에 대해 자세히 알아보려면 다음 섹션을 참고하세요.
트레이스 데이터 필터링
관심 있는 정보만 표시하려면 필터를 적용하세요. 필터는 표시되는 데이터를 제한합니다. 예를 들어 서비스 이름과 상태별로 필터링할 수 있습니다. 또는 애플리케이션을 App Hub에 배포한 경우 애플리케이션의 트레이스 데이터만 보거나 애플리케이션에 속한 특정 서비스 또는 워크로드의 트레이스 데이터만 볼 수 있습니다.
필터를 추가하거나 삭제하면 Trace 탐색기 페이지에 표시되는 데이터가 새로고침되고 적용된 모든 필터와 일치하는 스팬만 표시됩니다.
ID로 트레이스 필터링
이슈 또는 문제를 해결할 때 이미 trace ID를 알고 있는 경우가 있습니다. 해당 trace를 탐색하려면 툴바로 이동하여 페이지 조회 trace 검색을 클릭하고 trace ID를 입력합니다.
유효한 ID를 입력하면 세부정보 플라이아웃이 열리고 trace 및 스팬에 대한 정보가 표시됩니다. 해당 창의 옵션을 사용하여 트레이스를 탐색할 수 있습니다. 예를 들어 스팬에서 키워드를 검색할 수 있습니다.
범위 필터 적용
스팬 필터 창에는 가장 일반적인 필터가 나열됩니다. 하위 카테고리에서 항목을 여러 개 선택할 수 있습니다. 필터를 추가하거나 삭제하면 필터 표시줄도 업데이트됩니다.
모든 메뉴의 값은 추적 데이터에서 파생됩니다. 메뉴에 텍스트가 없는 옵션이 포함된 경우 해당 옵션은 해당 속성이 포함되지 않은 범위를 나타냅니다.
일반적으로 사용할 수 있는 범위 필터는 다음과 같습니다.
- OpenTelemetry 서비스:
service.name속성을 기준으로 필터링합니다. - 스팬 이름: 스팬의 이름입니다.
- 스팬 상태: 요청 상태입니다. 값에 관한 자세한 내용은 OpenTelemetry SpanStatus 문서를 참고하세요.
- Duration: 스팬의 지속 시간입니다.
- 스팬 종류: 스팬 간의 관계를 설명합니다. 값에 관한 자세한 내용은 OpenTelemetry SpanKind 문서를 참고하세요.
- App Hub 애플리케이션:
gcp.apphub.application.id리소스 속성으로 필터링합니다. - App Hub 서비스:
gcp.apphub.service.id리소스 속성으로 필터링합니다. - App Hub 워크로드:
gcp.apphub.workload.id리소스 속성으로 필터링합니다.
스팬 필터 창에 나열되지 않은 속성으로 필터링하려면 필터 표시줄을 사용하세요.
필터 표시줄 사용
필터 표시줄을 사용하면 사전 정의된 필터 키와 선택한 값을 사용하여 필터를 적용할 수 있으며, 키와 값을 모두 입력할 수도 있습니다.
필터를 추가하려면 필터 추가를 선택한 다음 다음 중 하나를 수행합니다.
- 스팬 이름과 같은 정의된 키를 선택한 다음 보조 메뉴에서 값을 선택합니다.
속성 필터 추가를 선택한 다음 맞춤 키와 값을 추가합니다. 자체 필터 키를 입력하는 경우 스팬의 속성 키와 동일한 구문을 사용합니다.
예를 들어 호스트 식별자로 필터링하려면 키를
host.id로 설정합니다. 마찬가지로 상태 코드로 필터링하려면 키를/http/status_code로 설정합니다. 이 시나리오에서는 값을200로 설정하여/http/status_code: 200필터를 생성할 수 있습니다. 필터가 모든 값과 일치하도록 하려면 모든 값을 선택합니다.
애플리케이션별 필터링
애플리케이션에 추가한 계측에서 생성된 trace 스팬에는 다음 리소스 속성이 포함될 수 있습니다.
gcp.apphub.application.{container,id,location}gcp.apphub.{workload,service}.{criticality_type,environment_type,id}
trace 탐색기 페이지에는 App Hub에 등록된 애플리케이션, 서비스, 워크로드가 메뉴에 나열된 다음 스팬 필터가 포함됩니다.
- App Hub 애플리케이션:
gcp.apphub.application.id리소스 속성으로 필터링합니다. - App Hub 서비스:
gcp.apphub.service.id리소스 속성으로 필터링합니다. - App Hub 워크로드:
gcp.apphub.workload.id리소스 속성으로 필터링합니다.
추적 스팬에 애플리케이션별 속성이 포함되도록 애플리케이션을 계측하는 방법은 애플리케이션 모니터링을 위한 계측을 참고하세요.
trace 탐색
이 섹션에서는 트레이스 컨텍스트에서 스팬을 탐색하는 방법을 설명합니다.
Trace 탐색기 페이지를 열고 구성합니다. 이 단계에 대한 자세한 내용은 집계된 트레이스 데이터 보기를 참고하세요.
스팬 또는 트레이스의 세부정보를 보려면 다음 중 하나를 수행하세요.
Trace 탐색기 페이지의 표 섹션으로 이동하여 표 섹션에서 항목을 선택합니다. 표의 행을 원하는 표 헤더별로 정렬할 수 있습니다. 필터를 적용하여 표에 표시되는 범위를 제한할 수 있습니다.
Trace 탐색기 페이지의 툴바로 이동하여 pageview trace 검색을 클릭하고 trace ID를 입력합니다.
세부정보 플라이아웃이 열리고 트레이스와 스팬이 표시됩니다. 선택한 스팬 또는 트레이스의 세부정보가 표시됩니다.
- 이름 열에는 호출 계층 구조가 표시되고 첫 번째 항목에는 트레이스 ID가 포함됩니다. 이 열에는 생성형 AI 이벤트 또는 로그 데이터의 사용 가능 여부를 나타내는 주석도 포함될 수 있습니다.
- 서비스 열은 OpenTelemetry 속성
service.name을 설정할 때 이 속성에서 추출된 이름입니다. 이 속성이 설정되지 않았고 서비스가 App Engine에서 실행되는 경우에는 App Engine 서비스 이름이 표시됩니다. 그렇지 않으면 서비스가 지정되지 않습니다. - 지연 시간 막대의 길이는 지연 시간 값을 나타냅니다.
- 지연 시간 막대의 색상은 상태를 나타냅니다. 파란색 지연 시간 막대는 성공적으로 완료되었음을 나타내고 빨간색 지연 시간 막대는 오류가 발생했음을 나타냅니다.
- 지연 시간 막대의 원은 로그 항목 또는 이벤트가 스팬과 연결되어 있음을 나타냅니다. 이 동작을 변경하려면 로그 및 이벤트 메뉴를 사용하세요.
트레이스를 탐색하려면 다음을 실행하세요.
포인터를 사용하여 다양한 범위를 선택합니다. 스팬을 선택하면 페이지의 탭이 새로고침되어 스팬의 속성, 로그 항목, 이벤트가 표시됩니다.
trace에서 키워드를 검색하려면 Trace에서 찾기 필드를 사용합니다.
검색은 스팬 이름, 서비스 이름, 속성 필드에만 적용됩니다. 일반 텍스트로만 검색할 수 있으며 로그, 이벤트, 메타데이터를 검색할 수 없습니다.
예를 들어
GET를 입력하면 대소문자를 무시하고 스팬 이름, 서비스 이름 또는GET를 표시하는 속성 창의 텍스트가 강조 표시됩니다.
속성, 로그 항목, 이벤트 보기
범위의 세부정보 플라이아웃에는 다음 각각에 대한 탭이 포함되어 있습니다.
속성: 이 탭에는 스팬에 연결된 라벨이 나열됩니다. 라벨에 대한 자세한 내용은 Trace 라벨을 참고하세요.
로그 및 이벤트: 이 탭에는
trace_id및span_id필드가 선택한 스팬과 일치하는 이벤트와 로그 항목이 표시됩니다. 볼 권한이 있는 로그 항목만 표시됩니다.이 탭에서 항목을 탐색하려면 keyboard_arrow_down 자세히 보기를 클릭합니다.
로그 탐색기 페이지를 사용하여 로그 데이터를 보려면 로그 보기를 클릭합니다. 쿼리가 특정 트레이스, 스팬, 시간 범위로 필터링되도록 설정되어 있습니다.
스택 트레이스: 사용 가능한 스택 트레이스를 나열합니다.
메타데이터 및 링크: 스팬에 대한 일반 정보를 나열합니다.
세부정보에는 입력/출력 탭도 포함될 수 있습니다. 이 탭에는 생성형 AI 이벤트가 표시됩니다.
생성형 AI 이벤트 보기
생성형 AI 에이전트와 관련된 이벤트를 보려면 입력/출력 탭을 사용하세요. 이 탭에는 OpenTelemetry 생성형 AI 시맨틱 규칙을 따르는 이벤트가 표시됩니다.
지원되는 구성은 두 가지입니다.
스팬에 속성으로 연결된 텍스트 기반 프롬프트와 응답입니다. 속성은 일부 특징이나 이벤트를 설명하는 키-값 쌍입니다. 예를 들어
gen_ai.system키의 값은 생성형 AI 기능을 제공하는 시스템을 식별합니다. 생성형 AI 속성의 키는gen_ai로 시작합니다.Cloud Storage 버킷에 저장된 멀티모달 프롬프트 및 대답 Cloud Trace는 추적 및 로그 데이터를 상호 연관시켜 이러한 이벤트를 식별합니다. 지원되는 구성에 대해 알아보려면 멀티모달 프롬프트 및 대답 수집 및 보기를 참고하세요.
다음 스크린샷은 스팬에 연결된 텍스트 기반 생성형 AI 이벤트가 Trace 탐색기 페이지에 렌더링되는 방식을 보여줍니다.
이전 스크린샷을 생성한 샘플 애플리케이션에 대해 알아보려면 OpenTelemetry로 LangGraph ReAct 에이전트 계측을 참고하세요.