Trace의 샘플 SQL 쿼리

미리보기

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

이 문서에는your Google Cloud project에 저장된 trace 데이터를 쿼리하는 데 특정한 샘플 쿼리가 포함되어 있습니다.

SQL 언어 지원

로그 애널리틱스 페이지에서 사용되는 쿼리는 몇 가지 예외를 제외하고 GoogleSQL 함수를 지원합니다.

다음 SQL 명령어는 로그 애널리틱스 페이지를 사용하여 실행된 SQL 쿼리에 지원되지 않습니다.

• DDL 및 DML 명령어
• 자바스크립트 사용자 정의 함수
• BigQuery ML 함수
• SQL 변수

다음은 BigQuery Studio 및 Looker Studio 페이지를 사용하거나 bq 명령줄 도구를 사용하여 연결된 데이터 세트를 쿼리할 때만 지원됩니다.

• 자바스크립트 사용자 정의 함수
• BigQuery ML 함수
• SQL 변수

권장사항

쿼리 기간을 설정하려면 기간 선택기를 사용하는 것이 좋습니다. 예를 들어 이전 주의 데이터를 보려면 기간 선택기에서 지난 7일 을 선택합니다. 또한 기간 선택기를 사용하여 시작 및 종료 시간을 지정하고, 둘러볼 시간을 지정하고, 시간대를 변경할 수 있습니다.

WHERE 절에 start_time 필드를 포함하면 시간 범위 선택기 설정은 사용되지 않습니다. 다음 예시에서는 TIMESTAMP_SUB 함수를 사용하여 데이터를 필터링하고 현재 시간에서 뒤돌아보는 간격을 지정할 수 있습니다.

WHERE
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

시간별로 필터링하는 방법에 대한 자세한 내용은 시간 함수 및 타임스탬프 함수를 참조하세요.

시작하기 전에

계정에 로그인합니다. Google Cloud 를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. Google Cloud신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $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 역할을 부여해 달라고 요청하세요.

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

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

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

이 페이지의 쿼리를 사용하는 방법

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

   로그 애널리틱스로 이동

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

2. 쿼리 창에서  SQL을 클릭한 후 쿼리를 복사하여 SQL 쿼리 창에 붙여넣습니다.

   다음은 _AllSpans 뷰를 쿼리하기 위한 FROM 절의 형식을 보여줍니다.

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

   FROM 절에는 다음 필드가 포함되어 있습니다.

   • PROJECT_ID: 프로젝트 식별자
   • LOCATION: 관측 가능성 버킷의 위치
   • _Trace는 관측 가능성 버킷의 이름입니다.
   • Spans는 데이터 세트의 이름입니다.
   • _AllSpans는 뷰의 이름입니다.
   참고: 경로의 구분 기호는 마침표 문자 (.)입니다. the Google Cloud project와 같은 경로 요소에 마침표 문자가 포함되어 있으면 모든 경로 필드가 작은따옴표 (`).
   로 래핑되는지 확인합니다.

BigQuery Studio 페이지에서 이 문서에 표시된 쿼리를 사용하거나 bq 명령줄 도구를 사용하려면 FROM 절을 수정하고 연결된 데이터 세트의 경로를 입력합니다. 예를 들어 프로젝트 myproject에 있는 my_linked_dataset이라는 연결된 데이터 세트의 _AllSpans 뷰를 쿼리하려면 경로는 `myproject.my_linked_dataset._AllSpans`입니다.

일반적인 사용 사례

이 섹션에는 커스텀 쿼리를 만드는 데 도움이 될 수 있는 몇 가지 일반적인 사용 사례가 나와 있습니다.

모든 trace 데이터 표시

_AllSpans 뷰를 쿼리하려면 다음 쿼리를 실행합니다.

-- Display all data.
SELECT *
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
-- Limit to 10 entries.
LIMIT 10

일반적인 스팬 정보 표시

시작 시간 및 기간과 같은 일반적인 스팬 정보를 표시하려면 다음 쿼리를 실행합니다.

SELECT
  start_time,
  -- Set the value of service name based on the first non-null value in the list.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
  name AS span_name,
  duration_nano,
  status.code AS status,
  trace_id,
  span_id
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
LIMIT 10

자세한 내용은 조건식을 참고하세요.

스팬 지연 시간의 50번째 및 99번째 백분위수 표시

각 RPC 서비스의 지연 시간의 50번째 및 99번째 백분위수를 표시하려면 다음 쿼리를 실행합니다.

SELECT
  -- Compute 50th and 99th percentiles for each service
  STRING(attributes['rpc.service']) || '/' || STRING(attributes['rpc.method']) AS rpc_service_method,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS duration_nano_p50,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS duration_nano_p99
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans whose kind field has a value of 2 (SPAN_KIND_SERVER).
  kind = 2
GROUP BY rpc_service_method

열거에 대한 자세한 내용은 OpenTelemetry: SpanKind 문서를 참고하세요.

결과를 그래픽으로 보려면 측정기준이 rpc_service_method로 설정된 차트를 만들면 됩니다. duration_nano_p50 값의 평균에 대한 측정항목과 duration_nano_p99 필드의 평균에 대한 측정항목을 두 개 추가할 수 있습니다.

trace 항목 필터링

쿼리에 필터를 적용하려면 WHERE 절을 추가합니다. 이 절에서 사용하는 문법은 필드의 데이터 유형에 따라 다릅니다. 이 섹션에서는 다양한 데이터 유형의 여러 예시를 제공합니다.

문자열 데이터 유형별 필터링

name 필드는 String으로 저장됩니다.

• name이 지정된 스팬만 분석하려면 다음 절을 사용합니다.

  -- Matches spans that have a name field.
  WHERE name IS NOT NULL
  

• name의 값이 "POST"인 스팬만 분석하려면 다음 절을 사용합니다.

  -- Matches spans whose name is POST.
  WHERE STRPOS(name, "POST") > 0
  

• name에 "POST" 값이 포함된 스팬만 분석하려면 와일드 카드와 함께 LIKE 연산자를 사용합니다.

  -- Matches spans whose name contains POST.
  WHERE name LIKE "%POST%"
  

정수 데이터 유형별 필터링

kind 필드는 0~5 사이의 값을 사용할 수 있는 정수입니다.

• kind가 지정된 스팬만 분석하려면 다음 절을 사용합니다.

  -- Matches spans that have field named kind.
  WHERE kind IS NOT NULL
  

• kind 값이 1 또는 2인 스팬을 분석하려면 다음 절을 사용합니다.

  -- Matches spans whose kind value is 1 or 2.
  WHERE kind IN (1, 2)
  

RECORD 데이터 유형별 필터링

trace 스키마의 일부 필드에는 RECORD 데이터 유형이 있습니다. 이러한 필드는 하나 이상의 데이터 구조를 저장하거나 동일한 데이터 구조의 반복 항목을 저장할 수 있습니다.

상태 또는 상태 코드로 필터링

status 필드는 데이터 유형이 RECORD인 필드의 예입니다. 이 필드는 code 및 message로 라벨이 지정된 멤버가 있는 하나의 데이터 구조를 저장합니다.

• status.code 필드의 값이 1인 경우에만 스팬을 분석하려면 다음 절을 추가합니다.

  -- Matches spans that have a status.code field that has a value of 1.
  WHERE status.code = 1
  

  status.code 필드는 정수로 저장됩니다.

• status 필드가 EMPTY가 아닌 스팬을 분석하려면 다음 절을 추가합니다.

  -- Matches spans that have status field. When the status field exists, it
  -- must contain a subfield named code.
  -- Don't compare status to NULL, because this field has a data type of RECORD.
  WHERE status.code IS NOT NULL
  

이벤트 또는 링크별 필터링

events 및 links 필드는 RECORD 데이터 유형으로 저장되지만 반복 필드입니다.

• 이벤트가 하나 이상 있는 스팬과 일치시키려면 다음 절을 사용합니다.

  -- Matches spans that have at least one event. Don't compare events to NULL.
  -- The events field has data type of RECORD and contains a repeated fields.
  WHERE ARRAY_LENGTH(events) > 0
  

• name 필드의 값이 message인 이벤트가 있는 스팬과 일치시키려면 다음 절을 사용합니다.

  WHERE
    -- Exists is true when any event in the array has a name field with the
    -- value of message.
    EXISTS(
      SELECT 1
      FROM UNNEST(events) AS ev
      WHERE ev.name = 'message'
    )
  

JSON 데이터 유형별 필터링

attributes 필드는 JSON 유형입니다. 각 개별 속성은 키-값 쌍입니다.

• attributes가 지정된 스팬만 분석하려면 다음 절을 사용합니다.

  -- Matches spans where at least one attribute is specified.
  WHERE attributes IS NOT NULL
  

• component라는 속성 키의 값이 "proxy"인 스팬만 분석하려면 다음 절을 사용합니다.

  -- Matches spans that have an attribute named component with a value of proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') = 'proxy'
  

  와일드 카드와 함께 LIKE 문을 사용하여 포함 테스트를 실행할 수도 있습니다.

  -- Matches spans that have an attribute named component whose value contains proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') LIKE '%proxy%'
  

trace 데이터 그룹화 및 집계

이 섹션에서는 스팬을 그룹화하고 집계하는 방법을 보여줍니다. 그룹화를 지정하지 않고 집계를 지정하면 SQL은 WHERE 절을 충족하는 모든 항목을 하나의 그룹으로 처리하므로 하나의 결과가 출력됩니다.

모든 SELECT 표현식은 그룹 필드에 포함되거나 집계되어야 합니다.

시작 시간별 스팬 그룹화

시작 시간별로 데이터를 그룹화하려면 타임스탬프를 HOUR과 같이 지정된 단위로 자르는 함수 TIMESTAMP_TRUNC, 를 사용합니다.

SELECT
  -- Truncate the start time to the hour. Count the number of spans per group.
  TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
  status.code AS code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans shows start time is within the previous 12 hours.
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 12 HOUR)
GROUP BY
  -- Group by hour and status code.
  hour, code
ORDER BY hour DESC

자세한 내용은 TIMESTAMP_TRUNC 문서 및 날짜/시간 함수를 참고하세요.

참고: start_time 필드를 WHERE 절에 포함하면 시간 범위 선택기 설정은 사용되지 않습니다.

상태 코드별 스팬 수

특정 상태 코드가 있는 스팬 수를 표시하려면 다음 쿼리를 실행합니다.

SELECT
  -- Count the number of spans for each status code.
  status.code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE status.code IS NOT NULL
GROUP BY status.code

status.code를 kind로 바꾸면 이전 쿼리는 kind 열거형의 각 값에 대한 스팬 수를 보고합니다. 마찬가지로 status.code를 name으로 바꾸면 쿼리 결과에 각 스팬 이름의 항목 수가 나열됩니다.

모든 스팬의 평균 기간 계산

스팬 이름을 기준으로 스팬 데이터를 그룹화한 후 평균 기간을 표시하려면 다음 쿼리를 실행합니다.

SELECT
  -- Group by name, and then compute the average duration for each group.
  name,
  AVG(duration_nano) AS nanosecs,
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY name
ORDER BY nanosecs DESC

서비스 이름별 평균 기간 및 백분위수 계산

다음 쿼리는 각 서비스의 스팬 수와 다양한 통계를 계산합니다.

SELECT
  -- Set the service name by the first non-null value.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,

  -- Count the number spans for each service name. Also compute statistics.
  COUNT(*) AS span_count,
  AVG(duration_nano) AS avg_duration_nano,
  MIN(duration_nano) AS min_duration_nano,
  MAX(duration_nano) AS max_duration_nano,

  -- Calculate percentiles for duration
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS p50_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(95)] AS p95_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS p99_duration_nano,

  -- Count the number of unique trace IDs. Also, collect up to 5 unique
  -- span names and status codes.
  COUNT(DISTINCT trace_id) AS distinct_trace_count,
  ARRAY_AGG(DISTINCT name IGNORE NULLS LIMIT 5) AS sample_span_names,
  ARRAY_AGG(DISTINCT status.code IGNORE NULLS LIMIT 5) AS sample_status_codes
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY service_name
ORDER BY span_count DESC

교차 열 검색

이 섹션에서는 쿼리 중인 뷰의 여러 열을 검색하는 데 사용할 수 있는 두 가지 접근 방식을 설명합니다.

• 토큰 기반 검색: 검색 위치와 검색어를 지정한 후 SEARCH 함수를 사용합니다. SEARCH 함수에는 데이터 검색 방법에 관한 특정 규칙이 있으므로 SEARCH 문서를 읽어보는 것이 좋습니다.

• 하위 문자열 기반 검색: 검색 위치와 문자열 리터럴을 제공한 후 CONTAINS_SUBSTR 함수를 사용합니다. 시스템은 대소문자를 구분하지 않는 테스트를 실행하여 표현식에 문자열 리터럴이 있는지 확인합니다. CONTAINS_SUBSTR 함수는 문자열 리터럴이 있으면 TRUE를 반환하고 그렇지 않으면 FALSE를 반환합니다. 검색 값은 STRING 리터럴이어야 하지만 리터럴 NULL은 아니어야 합니다.

여러 뷰 쿼리

쿼리 문은 테이블 또는 표현식을 한 개 이상 검색하고 계산된 결과 행을 반환합니다. 예를 들어 쿼리 문을 사용하여 다양한 방식으로 서로 다른 테이블 또는 데이터 세트에 대한 SELECT 문의 결과를 병합한 후 결합된 데이터에서 해당 열을 선택할 수 있습니다.

뷰를 조인하려면 다음 제한사항이 적용됩니다.

1. 뷰의 위치는 다음 중 하나를 충족합니다.

   • 모든 뷰의 위치가 동일합니다.
   • 모든 뷰가 global 또는 us 위치에 있습니다.

2. 스토리지 리소스에서 고객 관리 암호화 키 (CMEK)를 사용하는 경우 다음 중 하나가 참입니다.

   • CMEK를 사용하는 스토리지 리소스는 동일한 Cloud KMS 키를 사용합니다.
   • CMEK를 사용하는 스토리지 리소스에는 공통 상위 항목이 있으며, 이 상위 항목은 스토리지 리소스와 동일한 위치에 있는 기본 Cloud KMS 키를 지정합니다.

   하나 이상의 스토리지 리소스에서 CMEK를 사용하는 경우 시스템은 공통 Cloud KMS 키 또는 상위 항목의 기본 Cloud KMS 키를 사용하여 조인으로 생성된 임시 데이터를 암호화합니다.

예를 들어 동일한 위치에 있는 두 개의 뷰가 있다고 가정해 보겠습니다. 그러면 다음 중 하나가 참인 경우 이러한 뷰를 조인할 수 있습니다.

• 스토리지 리소스에서 CMEK를 사용하지 않습니다.
• 하나의 스토리지 리소스는 CMEK를 사용하고 다른 스토리지 리소스는 CMEK를 사용하지 않습니다.
• 두 스토리지 리소스 모두 CMEK를 사용하며 동일한 Cloud KMS 키를 사용합니다.

• 두 스토리지 리소스 모두 CMEK를 사용하지만 서로 다른 키를 사용합니다. 하지만 리소스는 스토리지 리소스와 동일한 위치에 있는 기본 Cloud KMS 키를 지정하는 상위 항목을 공유합니다.

  예를 들어 로그 버킷 및 관측 가능성 버킷의 리소스 계층 구조에 동일한 조직이 포함되어 있다고 가정해 보겠습니다. 해당 조직의 경우 스토리지 위치에 동일한 기본 Cloud KMS 키를 사용하여 Cloud Logging 및 관측 가능성 버킷의 기본 리소스 설정을 구성한 경우 이러한 버킷의 뷰를 조인할 수 있습니다.

trace ID를 사용하여 trace 및 로그 데이터 조인

다음 쿼리는 스팬 및 trace ID를 사용하여 로그 및 trace 데이터를 조인합니다.

SELECT
  T.trace_id,
  T.span_id,
  T.name,
  T.start_time,
  T.duration_nano,
  L.log_name,
  L.severity,
  L.json_payload
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans` AS T
JOIN
  `PROJECT_ID.LOCATION._Default._AllLogs` AS L
ON
  -- Join log and trace data by both the span ID and trace ID.
  -- Don't join only on span ID, this field isn't globally unique.
  T.span_id = L.span_id
  -- A regular expression is required because the storage format of the trace ID
  -- differs between a log view and a trace view.
  AND T.trace_id = REGEXP_EXTRACT(L.trace, r'/([^/]+)$')
WHERE T.duration_nano > 1000000
LIMIT 10

쿼리의 응답에는 trace 및 스팬 ID가 나열되어 있으므로 이를 개별적으로 쿼리하여 추가 정보를 수집할 수 있습니다. 또한 결과에는 로그 항목의 심각도와 JSON 페이로드가 나열됩니다.

다음 단계

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

SQL 참고 문서 또는 기타 예시는 다음 문서를 참고하세요.

• 함수, 연산자, 조건부.
• 검색 함수.
• 쿼리 문법.
• Cloud Logging의 샘플 SQL 쿼리.