트레이스 쿼리 및 분석

모니터링 가능성 분석을 사용하면 Cloud Trace 데이터에 SQL 쿼리를 실행하여 성능 추세를 파악하고, 집계 통계를 생성하고, 결과를 차트와 표로 시각화할 수 있습니다. 프로젝트에서 저장한 모든 추적 데이터를 포함하는 기본 _AllSpans 뷰에 대해 쿼리가 실행되며 결과를 커스텀 대시보드에 저장할 수 있습니다.

개별 trace, 스팬 또는 스팬 속성을 검사하려면 Trace 탐색기 페이지를 사용하세요. 자세한 내용은 trace 찾기 및 탐색을 참고하세요.

연결된 BigQuery 데이터 세트 정보

추적 데이터를 쿼리하거나 추적 및 로그 데이터를 쿼리하는 데 연결된 BigQuery 데이터 세트가 필요하지 않습니다. 이러한 시나리오에서는 모니터링 가능성 분석 페이지를 사용할 수 있습니다. 로그 데이터 쿼리에 관한 자세한 내용은 관측 가능성 분석으로 로그 쿼리 및 분석을 참고하세요.

다음 작업을 수행하려면 연결된 BigQuery 데이터 세트가 필요합니다.

• 트레이스 데이터를 다른 BigQuery 데이터 세트와 조인합니다.
• BigQuery Studio 페이지 또는 데이터 스튜디오와 같은 다른 서비스에서 트레이스 데이터를 쿼리합니다.
• BigQuery 예약된 슬롯에서 쿼리를 실행하여 관측 가능성 분석 쿼리의 성능을 향상시킵니다.
• 알림 정책으로 SQL 쿼리 결과 모니터링

이 문서에서는 연결된 BigQuery 데이터 세트를 만드는 방법이나 예약된 슬롯에서 쿼리를 실행하도록 관측 가능성 분석을 구성하는 방법을 설명하지 않습니다. 이러한 주제에 대한 자세한 내용은 연결된 BigQuery 데이터 세트 만들기를 참고하세요.

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. 관측 가능성 분석 페이지를 로드하고, 추적 데이터에 대한 비공개 쿼리를 작성, 실행, 저장하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

   • 관측 가능성 뷰 접근자 (roles/observability.viewAccessor) 권한이 있어야 합니다. 이 역할은 IAM 조건을 지원하므로 특정 뷰에 대한 권한 부여를 제한할 수 있습니다. 역할 부여에 조건을 연결하지 않으면 주 구성원이 모든 관측 가능성 뷰에 액세스할 수 있습니다.
   • 프로젝트의 모니터링 가능성 분석 사용자 (roles/observability.analyticsUser) 이 역할에는 비공개 쿼리를 저장하고 실행하고 공유 쿼리를 실행하는 데 필요한 권한이 포함되어 있습니다.

   역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

   커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

스키마 표시

스키마는 필드와 데이터 유형을 포함하여 데이터가 저장되는 방식을 정의합니다. 이 정보는 스키마에 따라 쿼리할 필드와 필드를 다른 데이터 유형으로 변환해야 하는지 여부가 결정되므로 중요합니다. 예를 들어 HTTP 요청의 평균 지연 시간을 계산하는 쿼리를 작성하려면 지연 시간 필드에 액세스하는 방법과 정수(예: 100)로 저장되는지 또는 문자열(예: "100")로 저장되는지 여부를 알아야 합니다. 지연 시간 데이터가 문자열로 저장된 경우 평균을 계산하기 전에 쿼리가 값을 숫자 값으로 형 변환해야 합니다.

스키마를 식별하려면 다음을 수행합니다.

1. Google Cloud 콘솔에서 manage_search 관측 가능성 분석 페이지로 이동합니다.

   모니터링 가능성 분석으로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

2. 뷰 메뉴에서 트레이스 섹션으로 이동한 다음 _Trace.Spans._AllSpans를 선택합니다.

   스키마 창이 업데이트됩니다. 관측 가능성 분석은 데이터 유형이 JSON인 경우 열의 필드를 자동으로 추론합니다. 추론된 필드가 데이터에 표시되는 빈도를 확인하려면 more_vert 옵션을 클릭하고 정보 및 설명 보기를 선택합니다.

   스키마에 대해 알아보려면 trace 데이터의 스토리지 스키마를 참고하세요.

   _Trace.Spans._AllSpans라는 뷰가 표시되지 않으면Google Cloud 프로젝트에 _Trace라는 관측 가능성 버킷이 포함되어 있지 않은 것입니다. 이 실패를 해결하는 방법은 추적 저장소 초기화 실패를 참고하세요.

trace 데이터 쿼리

이 섹션에서는 트레이스 데이터를 쿼리하는 데 사용할 수 있는 방법을 설명합니다.

• 시스템 정의 쿼리를 로드하고, 이 쿼리를 수정하고, 쿼리를 실행합니다.
• 맞춤 쿼리를 입력하고 실행합니다. 예를 들어 기존 쿼리를 붙여넣거나 직접 작성할 수 있습니다. 맞춤 쿼리에는 조인, 중첩된 쿼리, 기타 복잡한 SQL 문이 포함될 수 있습니다. 예시는 샘플 SQL 쿼리를 참고하세요.
• 메뉴를 선택하여 쿼리를 빌드한 다음 해당 쿼리를 실행합니다. 관측 가능성 분석은 선택한 항목을 SQL 쿼리로 변환하며, 이 쿼리는 확인하고 수정할 수 있습니다.

시스템 정의 쿼리 로드, 수정, 실행

1. Google Cloud 콘솔에서 manage_search 관측 가능성 분석 페이지로 이동합니다.

   모니터링 가능성 분석으로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

2. 뷰 메뉴에서 트레이스 섹션으로 이동한 다음 _Trace.Spans._AllSpans를 선택합니다.

   _Trace.Spans._AllSpans라는 뷰가 표시되지 않으면Google Cloud 프로젝트에 _Trace라는 관측 가능성 버킷이 포함되어 있지 않은 것입니다. 이 실패를 해결하는 방법은 추적 저장소 초기화 실패를 참고하세요.

3. 다음 중 하나를 수행합니다.

   • 메뉴 선택으로 쿼리를 정의할 수 있는 쿼리 빌더를 사용하는 시스템 정의 쿼리를 로드하려면 쿼리 창에 쿼리 빌더가 표시되어 있는지 확인하세요. SQL 편집기가 표시되면 tune 빌더를 클릭합니다.

   • JSON 값을 추출하는 시스템 정의 쿼리를 로드하려면 쿼리 창에 SQL 편집기가 표시되어야 합니다. 이 창에 쿼리 빌더가 표시되면 code SQL을 클릭합니다.

4. 스키마 창에서 쿼리를 선택한 다음 덮어쓰기를 클릭합니다.

   쿼리 창에 시스템 정의 쿼리가 표시됩니다. 쿼리 빌더 모드를 선택했지만 SQL 쿼리를 보려면 code SQL을 클릭합니다.

5. 선택사항: 쿼리를 수정합니다.

6. 쿼리를 실행하려면 툴바로 이동하여 쿼리 실행을 선택합니다.

   모니터링 가능성 분석은 쿼리 결과를 표로 표시합니다. 하지만 차트를 만들 수 있으며 표나 차트를 커스텀 대시보드에 저장할 수도 있습니다. 자세한 내용은 SQL 쿼리 결과 차트로 표시를 참고하세요.

   툴바에 BigQuery에서 실행이 표시되면 기본 쿼리 엔진을 사용하도록 관측 가능성 분석을 전환해야 합니다. 이 설정을 변경하려면 쿼리 창의 툴바에서 settings 설정을 클릭한 다음 애널리틱스 (기본값)를 선택합니다.

맞춤 쿼리 입력 및 실행

SQL 쿼리를 입력하려면 다음을 수행합니다.

1. Google Cloud 콘솔에서 manage_search 관측 가능성 분석 페이지로 이동합니다.

   모니터링 가능성 분석으로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

2. 쿼리 창에서 code SQL을 클릭합니다.

   • 기간을 지정하려면 기간 선택기를 사용하는 것이 좋습니다. timestamp 필드를 지정하는 WHERE 절을 추가하면 이 값이 기간 선택기의 설정을 재정의하고 해당 선택기는 사용 중지됩니다.

   • 예시는 샘플 SQL 쿼리를 참고하세요.

   • SQL 편집기에 _Trace.Spans._AllSpans 뷰의 정규화된 이름이 표시됩니다. 형식은 다음과 같습니다.

     FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`

     이전 표현식의 필드는 다음과 같은 의미를 갖습니다.

     • PROJECT_ID: 프로젝트 식별자
     • LOCATION: 관측 가능성 버킷의 위치입니다.

     쿼리 창에 FROM 문을 참조하는 오류 메시지가 표시되면 뷰를 찾을 수 없습니다. 이 실패를 해결하는 방법은 뷰가 존재하지 않는다는 오류 메시지를 참고하세요.

3. 쿼리를 실행하려면 툴바로 이동하여 쿼리 실행을 선택합니다.

   모니터링 가능성 분석은 쿼리 결과를 표로 표시합니다. 하지만 차트를 만들 수 있으며 표나 차트를 커스텀 대시보드에 저장할 수도 있습니다. 자세한 내용은 SQL 쿼리 결과 차트로 표시를 참고하세요.

   툴바에 BigQuery에서 실행이 표시되면 기본 쿼리 엔진을 사용하도록 관측 가능성 분석을 전환해야 합니다. 이 설정을 변경하려면 쿼리 창의 툴바에서 settings 설정을 클릭한 다음 애널리틱스 (기본값)를 선택합니다.

쿼리 빌드, 수정, 실행

쿼리 빌더 인터페이스를 사용하면 메뉴에서 선택하여 쿼리를 빌드할 수 있습니다. 모니터링 가능성 분석은 선택 항목을 SQL 쿼리로 변환하며, 이 쿼리는 확인하고 수정할 수 있습니다. 예를 들어 쿼리 빌더 인터페이스를 사용하여 시작한 다음 SQL 편집기로 전환하여 쿼리를 미세 조정할 수 있습니다.

모니터링 가능성 분석은 항상 쿼리 빌더 인터페이스의 메뉴 선택을 SQL 쿼리로 변환할 수 있습니다. 하지만 모든 SQL 쿼리가 쿼리 빌더 인터페이스로 표현될 수 있는 것은 아닙니다. 예를 들어 조인이 있는 쿼리는 이 인터페이스로 표현할 수 없습니다.

쿼리를 빌드하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 manage_search 관측 가능성 분석 페이지로 이동합니다.

   모니터링 가능성 분석으로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

2. 쿼리 창에 SQL 편집기가 표시되면 tune 빌더를 선택합니다. 그러면 쿼리 빌더 창이 열립니다.

3. 소스 메뉴를 사용하여 쿼리할 보기를 선택합니다. 선택한 항목은 SQL 쿼리의 FROM 절에 매핑됩니다.

4. 선택사항: 다음 메뉴를 사용하여 결과 표를 제한하거나 서식을 지정합니다.

   • 모든 필드 검색: 일치하는 문자열을 검색합니다. 선택한 항목은 SQL 쿼리의 WHERE 절에 매핑됩니다.

   • 열: 결과 표에 표시할 열을 선택합니다. 선택한 항목은 SQL 쿼리의 SELECT 절에 매핑됩니다.

     이 메뉴에서 필드 이름을 선택하면 대화상자가 열립니다. 이 대화상자에서는 다음 작업을 할 수 있습니다.

     • 메뉴를 사용하여 데이터를 집계하거나 그룹화합니다.

       구문 오류를 방지하기 위해 한 열에 적용하는 집계 및 그룹화는 다른 열에도 자동으로 적용됩니다. 항목을 집계하고 그룹화하는 방법의 예는 쿼리 빌더를 사용하여 데이터 그룹화 및 집계를 참고하세요.

     • 모든 유형의 값을 지정된 다른 데이터 유형으로 변환합니다. 자세한 내용은 CAST 문서를 참고하세요.

     • 정규 표현식을 사용하여 값의 하위 문자열을 추출합니다. 자세한 내용은 REGEXP_EXTRACT 문서를 참고하세요.

   • 필터: 특정 속성 또는 스팬 ID를 포함하는 스팬으로 쿼리를 제한하려는 경우 필터를 추가합니다. 메뉴에 사용 가능한 모든 필터 옵션이 표시됩니다. 선택한 항목은 SQL 쿼리의 WHERE 절에 매핑됩니다.

   • 정렬 기준: 정렬할 열과 정렬이 오름차순인지 내림차순인지 설정합니다. 선택한 항목은 SQL 쿼리의 ORDER BY 절에 매핑됩니다.

   • 한도: 결과 테이블의 최대 행 수를 설정합니다. 선택한 항목은 SQL 쿼리의 LIMIT 절에 매핑됩니다.

5. 쿼리를 실행하려면 툴바로 이동하여 쿼리 실행을 선택합니다.

   모니터링 가능성 분석은 쿼리 결과를 표로 표시합니다. 하지만 차트를 만들 수 있으며 표나 차트를 커스텀 대시보드에 저장할 수도 있습니다. 자세한 내용은 SQL 쿼리 결과 차트로 표시를 참고하세요.

   툴바에 BigQuery에서 실행이 표시되면 기본 쿼리 엔진을 사용하도록 관측 가능성 분석을 전환해야 합니다. 이 설정을 변경하려면 쿼리 창의 툴바에서 settings 설정을 클릭한 다음 애널리틱스 (기본값)를 선택합니다.

예: 쿼리 빌더를 사용하여 데이터를 그룹화하고 집계하기

쿼리 빌더에서 열을 선택하면 각 필드에 그룹화 및 집계를 추가할 수 있는 메뉴가 포함됩니다. 그룹화를 사용하면 하나 이상의 열의 값을 기반으로 데이터를 그룹으로 정리할 수 있으며, 집계를 사용하면 이러한 그룹에 대해 계산을 실행하여 단일 값을 반환할 수 있습니다.

열 요소에서 선택한 각 필드에는 다음 옵션이 포함된 메뉴가 연결되어 있습니다.

• 없음: 이 필드로 그룹화하거나 집계하지 않습니다.
• 집계: 필드에 집계가 선택된 경우를 제외하고 열 요소에 나열된 필드를 그룹화합니다. 이러한 필드의 경우 각 그룹화의 모든 항목에 작업을 실행하여 값을 계산합니다. 작업은 필드의 평균을 계산하거나 각 그룹의 항목 수를 계산하는 것과 같은 작업을 수행할 수 있습니다.
• 그룹화 기준: 열 요소에 나열된 모든 필드를 기준으로 항목을 그룹화합니다.

이 예시에서는 쿼리 빌더를 사용하여 시작 시간, 스팬 이름, 스팬 종류별로 스팬을 그룹화한 다음 각 그룹의 평균 지속 시간을 나노초 단위로 계산하는 방법을 보여줍니다.

1. 열 메뉴에서 start_time, name, kind, duration_nano 필드를 선택합니다.
2. 시작 시간을 시간 단위로 자르려면 start_time 열의 메뉴를 펼치고 그룹화 기준을 선택합니다. 세부사항 메뉴가 시간으로 설정되어 있는지 확인합니다.

3. 적용을 클릭합니다.

   열에 대해 그룹화 기준을 선택하면 시스템에서 모든 열을 기준으로 항목을 그룹화합니다. 이 예시에서는 항목이 start_time, 스팬 이름, 스팬 종류, 기간 값의 잘린 값으로 그룹화됩니다.

   하지만 이 예의 목표는 잘린 시간, 스팬 이름, 스팬 종류별로 항목을 그룹화한 다음 각 그룹의 평균 기간을 계산하는 것입니다. 다음 단계에서는 그룹화를 수정하고 집계를 추가합니다.

4. duration_nano 필드의 메뉴를 펼치고 집계를 선택한 다음 집계 필드를 평균으로 설정합니다.

   쿼리를 실행하면 각 행은 잘린 시간, 스팬 이름, 스팬 종류로 구성된 그룹에 해당합니다. 각 행의 마지막 항목은 해당 그룹의 모든 항목에 대한 평균 기간입니다.

   이 쿼리 결과는 다음과 유사합니다.

   +-----------------------------------+----------------+----------+-----------------------+
   | Row | hour_timestamp              | span_name      | kind     | average_duration_nano |
   |     | TIMESTAMP                   | STRING         | INTEGER  | FLOAT                 |
   +-----+-----------------------------+-----------+---------------+-----------------------+
   | 1   | 2025-10-09 13:00:00.000 EDT | http.receive   | 3        | 122138.22813990474
   | 2   | 2025-10-09 13:00:00.000 EDT | query.request  | 1        | 6740819304.390297
   | 3   | 2025-10-09 13:00:00.000 EDT | client.handler | 2        | 6739339098.409376
   

5. 쿼리에 여러 집계를 포함할 수 있습니다. 예를 들어 각 그룹의 항목 수를 계산하는 열을 추가하려면 다음 단계를 따르세요.

   1. 열 요소에서 열 추가를 클릭합니다.
   2. 모두 (*)를 선택합니다.
   3. 대화상자에서 집계를 선택하고 집계에 개수를 선택한 다음 적용을 선택합니다.

   이 변경사항으로 인해 그룹화는 동일하게 유지됩니다. 항목은 잘린 시작 시간, 스팬 이름, 스팬 종류별로 그룹화됩니다. 하지만 각 그룹에 대해 쿼리는 평균 기간과 항목 수를 계산합니다.

이전 예의 해당 SQL 쿼리는 다음과 같습니다.

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.us._Trace.Spans._AllSpans` )
SELECT
  -- Report the truncated start time, span name, span kind, average duration and number
  -- of entries for each group.
  TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
  name AS span_name,
  kind,
  AVG( duration_nano ) AS average_duration_nano,
  COUNT( * ) AS count_all
FROM
  scope_query
GROUP BY
  TIMESTAMP_TRUNC( start_time, HOUR ),
  name,
  kind
LIMIT
  100

다음 단계

• Trace 저장소 개요
• SQL 쿼리 저장 및 공유
• SQL 쿼리 결과 차트로 표시
• 샘플 SQL 쿼리
• 연결된 BigQuery 데이터 세트 만들기