트레이스 쿼리 및 분석

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '현재 상태 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 문서에서는 SQL 기반 쿼리 인터페이스를 제공하는 로그 애널리틱스를 사용하여 trace 데이터를 쿼리하고 분석하는 방법을 설명합니다. SQL을 사용하면 집계 분석을 수행하여 유용한 정보를 생성하고 추세를 파악할 수 있습니다. 쿼리 결과를 보려면 표 또는 차트를 사용하세요. 이러한 표와 차트를 커스텀 대시보드에 저장할 수도 있습니다.

개별 trace 또는 스팬을 보거나 탐색하거나 스팬에 연결된 속성을 보려면 Trace 탐색기 페이지를 사용하세요. 이 페이지에 대한 자세한 내용은 trace 찾기 및 탐색을 참조하세요.

trace의 경우 _Trace라는 관측 가능성 버킷을 쿼리할 수 있습니다. 하나의 뷰(_AllSpans)를 쿼리할 수 있습니다. trace 데이터가 저장되는 방법에 대한 자세한 내용은 스토리지 개요를 참조하세요.

연결된 BigQuery 데이터 세트 정보

trace 데이터를 쿼리하거나 trace 및 로그 데이터를 쿼리하는 데 연결된 BigQuery 데이터 세트가 필요하지 않습니다. 이러한 시나리오에서는 로그 애널리틱스 페이지를 사용할 수 있습니다. 로그 데이터 쿼리에 대한 자세한 내용은 로그 애널리틱스로 로그 쿼리 및 분석을 참조하세요.

다음 중 하나를 수행하려면 연결된 BigQuery 데이터 세트가 필요합니다.

• trace 데이터를 다른 BigQuery 데이터 세트와 조인합니다.
• BigQuery Studio 페이지 또는 Looker Studio와 같은 다른 서비스에서 trace 데이터를 쿼리합니다.
• 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. 로그 애널리틱스 페이지를 로드하고, trace 데이터에 대해 비공개 쿼리를 작성, 실행, 저장하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

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

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

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

스키마 표시

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

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

1. 콘솔에서 로그 애널리틱스 페이지로 이동합니다. Google Cloud

   로그 애널리틱스로 이동

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

2. 뷰 메뉴에서 trace 섹션으로 이동한 후 _Trace.Spans._AllSpans를 선택합니다.

   스키마 창이 업데이트됩니다. 데이터 유형이 JSON인 경우 로그 애널리틱스는 열의 필드를 자동으로 추론합니다. 이러한 추론된 필드가 데이터에 표시되는 빈도를 보려면 옵션을 클릭하고 정보 및 설명 보기를 선택합니다.

   스키마에 대한 자세한 내용은 trace 데이터의 스토리지 스키마를 참조하세요.

   _Trace.Spans._AllSpans라는 뷰가 표시되지 않으면 Google Cloud 프로젝트에 _Trace라는 관측 가능성 버킷이 포함되어 있지 않은 것입니다. 이 실패를 해결하는 방법에 대한 자세한 내용은 trace 스토리지 초기화 실패를 참조하세요.

trace 데이터 쿼리

이 섹션에서는 trace 데이터를 쿼리하는 데 사용할 수 있는 접근 방식을 설명합니다.

• 시스템 정의 쿼리를 로드하고 이 쿼리를 수정한 후 쿼리를 실행합니다.
• 커스텀 쿼리를 입력하고 실행합니다. 예를 들어 보유하고 있는 쿼리를 붙여넣거나 쿼리를 작성할 수 있습니다. 커스텀 쿼리에는 조인, 중첩된 쿼리, 기타 복잡한 SQL 문이 포함될 수 있습니다. 예시는 샘플 SQL 쿼리를 참조하세요.
• 메뉴에서 선택하여 쿼리를 빌드한 후 해당 쿼리를 실행합니다. 로그 애널리틱스는 선택 항목을 SQL 쿼리로 변환하며, 이 쿼리를 보고 수정할 수 있습니다.

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

1. 콘솔에서 로그 애널리틱스 페이지로 이동합니다. Google Cloud

   로그 애널리틱스로 이동

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

   참고: 로그 애널리틱스 페이지의 창에 '로그 애널리틱스 시작하기' 메시지가 표시되면 창에서 닫기를 클릭합니다.

2. 뷰 메뉴에서 trace 섹션으로 이동한 후 _Trace.Spans._AllSpans를 선택합니다.

   _Trace.Spans._AllSpans라는 뷰가 표시되지 않으면 Google Cloud 프로젝트에 _Trace라는 관측 가능성 버킷이 포함되어 있지 않은 것입니다. 이 실패를 해결하는 방법에 대한 자세한 내용은 trace 스토리지 초기화 실패를 참조하세요.

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

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

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

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

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

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

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

   로그 애널리틱스는 쿼리 결과를 표에 표시합니다. 하지만 차트를 만들 수 있으며 표나 차트를 커스텀 대시보드에 저장할 수도 있습니다. 자세한 내용은 SQL 쿼리 결과 차트로 표시를 참조하세요.

   툴바에 BigQuery에서 실행이 표시되면 로그 애널리틱스를 전환하여 기본 쿼리 엔진을 사용해야 합니다. 이 변경사항을 적용하려면 쿼리 창의 툴바에서 설정 을 클릭한 후 애널리틱스 (기본값)을 선택합니다.

커스텀 쿼리 입력 및 실행

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

1. 콘솔에서 로그 애널리틱스 페이지로 이동합니다. Google Cloud

   로그 애널리틱스로 이동

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

   참고: 로그 애널리틱스 페이지의 창에 '로그 애널리틱스 시작하기' 메시지가 표시되면 창에서 닫기를 클릭합니다.

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

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

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

   • SQL 편집기에는 _Trace.Spans._AllSpans 뷰의 정규화된 이름이 다음 형식으로 표시됩니다.

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

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

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

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

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

   로그 애널리틱스는 쿼리 결과를 표에 표시합니다. 하지만 차트를 만들 수 있으며 표나 차트를 커스텀 대시보드에 저장할 수도 있습니다. 자세한 내용은 SQL 쿼리 결과 차트로 표시를 참조하세요.

   툴바에 BigQuery에서 실행이 표시되면 로그 애널리틱스를 전환하여 기본 쿼리 엔진을 사용해야 합니다. 이 변경사항을 적용하려면 쿼리 창의 툴바에서 설정 을 클릭한 후 애널리틱스 (기본값)을 선택합니다.

쿼리 빌드, 수정, 실행

쿼리 빌더 인터페이스를 사용하면 메뉴에서 선택하여 쿼리를 빌드할 수 있습니다. 로그 애널리틱스는 선택 항목을 SQL 쿼리로 변환하며, 이 쿼리를 보고 수정할 수 있습니다. 예를 들어 쿼리 빌더 인터페이스를 사용하여 시작한 후 SQL 편집기로 전환하여 쿼리를 구체화할 수 있습니다.

로그 애널리틱스는 항상 쿼리 빌더 인터페이스의 메뉴 선택 항목을 SQL 쿼리로 변환할 수 있습니다. 하지만 모든 SQL 쿼리를 쿼리 빌더 인터페이스로 나타낼 수는 없습니다. 예를 들어 조인이 있는 쿼리는 이 인터페이스로 나타낼 수 없습니다.

참고: 쿼리하려는 필드가 쿼리 빌더 인터페이스에 나열되지 않는 경우가 있을 수 있습니다. 열의 데이터 유형이 JSON인 경우 로그 애널리틱스는 열의 필드를 자동으로 추론합니다. 쿼리에서 자동으로 추론되지 않은 JSON 필드를 사용하려면 SQL 편집기로 전환하여 쿼리를 작성합니다.

쿼리를 생성하려면 다음을 수행합니다.

1. 콘솔에서 로그 애널리틱스 페이지로 이동합니다. Google Cloud

   로그 애널리틱스로 이동

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

   참고: 로그 애널리틱스 페이지의 창에 '로그 애널리틱스 시작하기' 메시지가 표시되면 창에서 닫기를 클릭합니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   로그 애널리틱스는 쿼리 결과를 표에 표시합니다. 하지만 차트를 만들 수 있으며 표나 차트를 커스텀 대시보드에 저장할 수도 있습니다. 자세한 내용은 SQL 쿼리 결과 차트로 표시를 참조하세요.

   툴바에 BigQuery에서 실행이 표시되면 로그 애널리틱스를 전환하여 기본 쿼리 엔진을 사용해야 합니다. 이 변경사항을 적용하려면 쿼리 창의 툴바에서 설정 을 클릭한 후 애널리틱스 (기본값)을 선택합니다.

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

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

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

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

다음은 항목을 그룹화한 후 특정 유형의 집계를 수행하는 쿼리를 구성하는 방법을 보여줍니다.

이 예에서는 쿼리 빌더를 사용하여 시작 시간, 스팬 이름, 스팬 종류별로 스팬을 그룹화하는 방법을 설명합니다. 그런 다음 각 그룹에 대해 쿼리는 평균 기간(나노초)을 계산합니다.

이 쿼리를 구성하려면 다음을 수행합니다.

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

3. 적용 을 클릭합니다.

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

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

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

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

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

   +-----------------------------------+----------------+----------+-----------------------+
   | Row | hour_timestamp              | span_name      | kind     | average_duation_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.global._Trace._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

다음 단계

• SQL 쿼리 저장 및 공유.
• SQL 쿼리 결과 차트로 표시
• 샘플 SQL 쿼리
• BigQuery에서 연결된 데이터 세트 쿼리