이 페이지는 Cloud Translation API를 통해 번역되었습니다.

trace 찾기 및 탐색

trace 데이터의 집계 표현을 보거나 개별 trace 또는 특정 라벨이 포함된 trace를 찾아보려면 Trace 탐색기 페이지를 사용하세요.

이 기능은 Google Cloud 프로젝트에서만 지원됩니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 관리 프로젝트를 선택합니다.

Trace 탐색기 페이지 정보

추적 데이터의 추세와 패턴을 파악할 수 있도록 지연 시간 데이터가 집계되어 차트에 표시됩니다. 기본 시각화인 히트맵은 색상을 사용하여 셀의 범위 수를 나타냅니다. 스팬이 많은 셀은 스팬이 적은 셀보다 어두운 색상으로 표시됩니다. 셀을 선택하거나 셀의 도움말을 활성화하여 자세한 정보를 확인할 수 있습니다. 다른 시각화를 사용하면 지연 시간을 백분위수 및 스팬 비율 정보로 볼 수 있습니다. 모든 시각화에서 포인터를 사용하여 x축을 확장할 수 있습니다. 선 차트의 경우 X축과 Y축을 확장할 수 있습니다.

문제를 조사할 때 특정 트레이스 또는 특정 속성이 있는 스팬만 확인해야 할 수 있습니다.

trace의 ID를 알고 있는 경우 툴바에서 trace 검색을 클릭한 다음 대화상자에 trace ID를 입력합니다. 그런 다음 트레이스에서 스팬과 속성을 검색하여 키워드를 찾을 수 있습니다 .
집계 데이터를 볼 때 필터를 적용하여 특정 스팬을 검색할 수 있습니다. 예를 들어 특정 서비스의 스팬만 표시하도록 데이터를 필터링할 수 있습니다. 그런 다음 오류를 보고하는 특정 서비스의 스팬만 표시하도록 두 번째 필터를 추가할 수 있습니다.

표 형식 데이터를 사용하면 개별 스팬의 세부정보를 확인하고 이상치를 식별할 수 있습니다. 예를 들어 지연 시간 값이 가장 높은 스팬을 찾으려면 스팬 탭을 선택한 다음 지연 시간별로 데이터를 정렬합니다. 오류를 생성하는 서비스를 찾으려면 스팬 상태별로 데이터를 필터링한 다음 스팬 및 서비스 이름별로 집계된 데이터를 표시하는 그룹화됨 탭을 선택합니다. 표의 각 행에는 세부정보 링크가 포함되어 있습니다.

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]
기본 trace 범위를 읽으려면 다음을 실행하세요. observability.scopes.get

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

역할에 대한 자세한 내용은 Identity and Access Management로 액세스 제어를 참조하세요.

집계된 trace 데이터 보기

trace 데이터에 대한 집계 정보를 보려면 다음 단계를 따르세요.

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

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

첫 번째 추적 데이터가 Google Cloud 프로젝트에 기록된 후 해당 데이터를 볼 수 있게 되기까지 몇 분 정도 걸릴 수 있습니다. 몇 분 후에도 trace 데이터가 표시되지 않으면 프로젝트에 표시할 데이터가 없거나 구성 문제가 있을 수 있습니다. 이 문제를 해결하는 방법은 문제 해결: Trace 인터페이스에 데이터가 없음을 참고하세요.
Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 관리 프로젝트를 선택합니다.
선택사항: 범위 요소를 사용하여 추적 데이터를 검색할 프로젝트를 구성합니다.
- 프로젝트에 저장된 추적 데이터를 표시하려면 범위 요소의 첫 번째 메뉴를 프로젝트 또는 _Default로 설정합니다. 이 두 설정은 동일합니다.
- 여러 프로젝트에 저장된 추적 데이터를 표시하려면 범위 요소의 첫 번째 메뉴를 펼치고 추적 범위를 선택한 다음 해당 프로젝트를 나열하는 추적 범위를 선택합니다. 선택하면 범위 메뉴에 추적 범위 아이콘()과 선택한 추적 범위의 이름이 표시됩니다.
반환되는 데이터는 검색된 프로젝트의 IAM 역할에 따라 다릅니다. 예를 들어 검색된 프로젝트에 액세스할 수 없는 Google Cloud 프로젝트가 포함된 경우 해당 프로젝트의 추적 데이터는 반환되지 않습니다.

자세한 내용은 trace 범위 만들기 및 관리를 참조하세요.
선택사항: 기간 선택기를 사용하거나 포인터를 사용하여 x축에서 범위를 강조 표시하여 기간을 업데이트합니다.

예를 들어 지연 시간 데이터에 추세가 있는지 확인하려면 이 선택기를 지난 2주로 설정할 수 있습니다.
툴바로 이동하여 기간 선택기를 2주 이상으로 설정합니다. 30일 동안 저장된 범위 데이터
트레이스 데이터의 패턴과 추세를 보여주는 차트를 살펴봅니다.
- 스팬 지연 시간 데이터에 대한 정보를 가져오려면 차트 보기 메뉴를 스팬 기간 (히트맵)으로 설정합니다. 색상 강도는 스팬 수에 비례합니다. 셀에 관한 정보를 보려면 포인터를 사용하세요. 도움말에는 스팬 수, 날짜 및 시간, 셀의 시간 간격이 표시됩니다.
  
  참고: 히트맵에서 셀을 선택하면 개별 스팬 또는 스팬 그룹을 나열하는 테이블이 업데이트됩니다.
- 지연 시간 추세를 보려면 차트 보기 메뉴를 범위 기간 (백분위수)로 설정합니다. 기간 차트에는 50번째, 90번째, 95번째, 99번째 백분위수가 표시됩니다.
- 시간에 따른 응답 상태를 보려면 차트 보기 메뉴를 스팬 비율로 설정합니다. 차트에는 프로젝트로 전송되는 스팬의 비율이 표시됩니다.
스팬 탭에는 개별 스팬이 나열되고 그룹화됨 탭에는 서비스 및 이름별로 그룹화된 스팬이 나열되는 표 형식 데이터를 살펴봅니다.

표의 각 행에는 스팬 또는 그룹화와 함께 세부정보 링크 및 일부 측정항목이 표시됩니다. 예를 들어 그룹화됨 탭의 측정항목에는 오류율과 그룹의 스팬 수가 포함됩니다.

이상치를 찾으려면 열 헤더를 선택하여 표를 정렬합니다.
표시할 스팬을 제한하는 필터를 추가합니다. 트레이스 데이터 필터링에 대해 자세히 알아보려면 다음 섹션을 참고하세요.

트레이스 데이터 필터링하기

관심 있는 정보만 표시하려면 필터를 적용하세요. 필터는 표시되는 데이터를 제한합니다. 예를 들어 서비스 이름과 상태별로 필터링할 수 있습니다. 또는 애플리케이션을 App Hub에 배포한 경우 애플리케이션의 trace 데이터만 보거나 애플리케이션에 속한 특정 서비스 또는 워크로드의 trace 데이터만 볼 수 있습니다.

필터를 추가하거나 삭제하면 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 데이터를 찾으려면 Trace 탐색기에서 스팬 필터 창으로 이동하여 App Hub 애플리케이션의 필터를 추가합니다.

애플리케이션 ID(gcp.apphub.application.id)별로 필터링하려면 App Hub 애플리케이션 메뉴를 사용합니다.
애플리케이션의 서비스(gcp.apphub.service.id)별로 필터링하려면 App Hub 서비스 메뉴를 사용합니다.
애플리케이션의 워크로드(gcp.apphub.workload.id)별로 필터링하려면 App Hub 워크로드 메뉴를 사용합니다.

trace 스팬에 애플리케이션별 속성이 포함되도록 애플리케이션을 계측하는 방법에 관한 자세한 내용은 애플리케이션 모니터링을 위한 계측을 참고하세요.

ID로 트레이스 찾기

이슈 또는 문제를 해결할 때 이미 trace ID를 알고 있는 경우가 있습니다. 이 trace를 탐색하려면 다음을 수행합니다.

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

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.
Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 관리 프로젝트를 선택합니다.
툴바로 이동하여 트레이스 검색을 클릭하고 트레이스 ID를 입력합니다.

유효한 ID를 입력하면 세부정보 플라이아웃이 열리고 trace 및 스팬에 대한 정보가 표시됩니다. 해당 창의 옵션을 사용하여 트레이스를 탐색할 수 있습니다. 예를 들어 스팬에서 키워드를 검색할 수 있습니다.

참고: 찾을 수 없는 trace ID를 입력하면 trace 데이터가 Trace 탐색기 페이지에서 검색되지 않는 프로젝트에 저장되어 있거나 trace 데이터를 볼 수 있는 IAM 역할이 없을 수 있습니다. 이러한 오류를 해결하려면 추적 데이터를 저장하는 프로젝트를 식별하세요. 각 프로젝트에서 IAM 역할이 트레이스 데이터를 볼 수 있도록 허용하는지 확인한 다음 범위 요소가 트레이스 데이터를 저장하는 모든 프로젝트를 검색하도록 구성되어 있는지 확인합니다. 자세한 내용은 trace 데이터를 검색할 프로젝트 목록 업데이트를 참고하세요.

trace 탐색

트레이스 또는 스팬을 보려면 다음을 수행하세요.

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

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

첫 번째 추적 데이터가 Google Cloud 프로젝트에 기록된 후 해당 데이터를 볼 수 있게 되기까지 몇 분 정도 걸릴 수 있습니다. 몇 분 후에도 trace 데이터가 표시되지 않으면 프로젝트에 표시할 데이터가 없거나 구성 문제가 있을 수 있습니다. 이 문제를 해결하는 방법은 문제 해결: Trace 인터페이스에 데이터가 없음을 참고하세요.
Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 관리 프로젝트를 선택합니다.
다음 중 하나를 수행합니다.
- Trace Explorer 페이지의 표 섹션으로 이동하여 스팬을 나열하거나 서비스 및 스팬 이름별로 데이터를 그룹화한 후 요약 정보를 나열하는 표에서 항목을 선택합니다.
- Trace 탐색기 페이지의 툴바로 이동하여 trace 검색을 클릭하고 trace ID를 입력합니다.
세부정보 플라이아웃이 열리고 트레이스와 스팬이 표시됩니다.
- 이름 열에는 호출 계층 구조가 표시되고 첫 번째 항목에는 트레이스 ID가 포함됩니다.
- 서비스 열은 OpenTelemetry 속성 service.name을 설정할 때 이 속성에서 추출된 이름입니다. 이 속성이 설정되지 않았고 서비스가 App Engine에서 실행되는 경우에는 App Engine 서비스 이름이 표시됩니다. 그렇지 않으면 서비스가 지정되지 않습니다.
- 지연 시간 막대의 길이는 지연 시간 값을 나타냅니다.
- 지연 시간 막대의 색상은 상태를 나타냅니다. 파란색 지연 시간 막대는 성공적으로 완료되었음을 나타내고 빨간색 지연 시간 막대는 오류가 발생했음을 나타냅니다.
- 지연 시간 막대의 원은 로그 항목 또는 이벤트가 스팬과 연결되어 있음을 나타냅니다. 이 동작을 변경하려면 로그 및 이벤트 메뉴를 사용하세요.
선택사항: Trace에서 찾기 필드를 사용하여 trace에서 스팬 이름, 서비스 이름, 속성을 검색합니다.

예를 들어 GET를 입력하면 대소문자를 무시하고 스팬 이름, 서비스 이름 또는 GET를 표시하는 속성 창의 텍스트가 강조 표시됩니다.

정규 표현식을 사용하여 검색할 수 없으며 로그, 이벤트, 메타데이터를 검색할 수 없습니다.
특정 스팬의 세부정보를 보려면 스팬을 선택하고 속성 및 이벤트를 확인합니다. 자세한 내용은 다음 섹션을 참고하세요.

속성 및 이벤트 보기

이 섹션에서는 라벨, 로그, 이벤트를 보는 방법을 설명합니다.

뷰 라벨

스팬에 연결된 라벨을 보려면 속성 탭으로 이동합니다. 라벨에 대한 자세한 내용은 Trace 라벨을 참고하세요.

로그 및 이벤트 보기

스팬과 관련된 로그 및 이벤트를 보려면 로그 및 이벤트 탭으로 이동합니다.

로그 항목을 보려면 자세히 보기를 클릭합니다.

로그 보기 버튼을 선택할 수도 있습니다. 그러면 특정 트레이스, 스팬, 시간 범위로 필터링하도록 쿼리가 설정된 로그 탐색기 페이지가 열립니다. 이 쿼리는 로그 항목을 반환하지 않을 수 있습니다.

생성형 AI 이벤트 보기

생성형 AI 에이전트와 관련된 이벤트를 보려면 GenAI 탭을 사용하세요. 이 탭은 Trace로 전송된 스팬이 생성형 AI 시스템의 OpenTelemetry 시맨틱 규칙을 따르는 경우에 사용할 수 있으며, 이 경우 이름이 gen_ai로 시작하는 메시지가 표시됩니다.

다음 스크린샷은 Trace 탐색기 페이지에서 생성형 AI 이벤트를 렌더링하는 방법을 보여줍니다.

trace 스팬 표시

이전 스크린샷을 생성한 샘플 애플리케이션에 관해 알아보려면 OpenTelemetry를 사용하여 LangGraph ReAct 에이전트 계측을 참고하세요.

속성은 일부 특징을 설명하는 키-값 쌍입니다. 다음은 생성형 AI 시스템의 속성 예시입니다.

gen_ai.system: 생성형 AI 기능을 제공하는 시스템을 식별합니다.
gen_ai.request.model: 요청이 전송되는 모델을 식별합니다.

이름이 'gen_ai'로 시작하는 이벤트는 일반적으로 생성형 AI 시스템의 개별 입력 또는 출력을 설명합니다. 이러한 입력과 출력에는 시스템 및 사용자 프롬프트, 도구 입력 및 출력, 모델 응답이 포함됩니다. 다음은 생성형 AI 시스템의 이벤트 예시입니다.

gen_ai.system.message: 생성형 AI 모델에 전송된 시스템 프롬프트를 기록하는 이벤트입니다. 시스템 프롬프트는 일반적으로 최종 사용자에게 표시되지 않으며 모델의 사용자 프롬프트 해석을 안내하는 모델에 대한 안내를 제공합니다.
gen_ai.user.message: 모델에 전송된 사용자 제공 프롬프트를 기록하는 이벤트입니다.
gen_ai.assistant.message: 모델의 출력을 기록하는 이벤트로, 도구 호출 기록을 포함하거나 텍스트 응답 출력을 포함할 수 있습니다. 메시지에는 애플리케이션에서 사용하지 않는 후보 응답이 포함될 수 있습니다.
gen_ai.choice: 애플리케이션에서 사용되는 후보 출력을 보고하는 데 사용되는 이벤트입니다.

스택 트레이스 보기

스택 트레이스를 보려면 스택 트레이스 탭을 사용합니다.

일반 정보 및 기타 메타데이터 보기

스팬에 대한 일반적인 정보와 다른 스팬에 대한 링크 테이블을 찾으려면 메타데이터 및 링크 탭을 확인합니다. 이 정보에는 다음이 포함됩니다.

스팬 ID: 스팬 ID는 0이 아닌 64비트 정수입니다. 자세한 내용은 TraceSpan을 참조하세요.
상위 스팬 ID
프로젝트 ID
시작 시간 및 종료 시간
다른 스팬에 대한 링크가 나열된 테이블

링크라는 테이블의 각 행에는 현재 스팬과 다른 스팬 간의 링크가 나열됩니다. 속성 필드에는 연결 대상 스팬의 키-값 쌍이 나열됩니다. Trace 필드는 연결 대상 스팬의 trace에 연결합니다. 이 필드에 현재 trace가 포함되어 있으면 연결 대상 스팬이 현재 스팬과 동일한 trace에 있습니다. 그렇지 않으면 필드에 trace ID가 포함됩니다. 링크에 대한 자세한 내용은 Links API 참조 페이지를 확인하세요.

트렌드 보기

애플리케이션에 업데이트를 배포한 후 업데이트가 응답 지연 시간에 영향을 미쳤는지 확인하는 것이 좋습니다. 업그레이드 전후의 지연 시간 데이터가 모두 표시되도록 시간 범위 선택기를 설정하여 지연 시간 데이터의 추세를 확인할 수 있습니다.

trace 데이터의 추세를 보려면 다음 단계를 따르세요.

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

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.
Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 관리 프로젝트를 선택합니다.
선택사항: 표시할 스팬을 구성하는 필터를 추가합니다.
툴바로 이동하여 기간 선택기를 2주 이상으로 설정합니다. 스팬 데이터는 30일 동안 저장됩니다.
선택사항: 차트 보기 메뉴의 선택사항을 변경합니다.