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

로그 애널리틱스로 로그 쿼리 및 분석

이 문서에서는 SQL 기반 쿼리 인터페이스를 제공하는 로그 애널리틱스를 사용하여 로그 데이터를 쿼리하고 분석하는 방법을 설명합니다. SQL을 사용하면 패턴과 일치하는 필드로 로그 항목을 계산하는 등의 작업을 실행할 수 있습니다. 로그 애널리틱스에서는 쿼리를 빌드하기 위한 SQL 편집기와 메뉴 기반 시스템을 제공합니다. 쿼리 결과를 보려면 표 형식을 사용하거나 데이터를 차트로 시각화할 수 있습니다. 차트를 맞춤 대시보드에 저장할 수 있습니다.

로그 버킷의 로그 뷰 또는 분석 뷰를 쿼리할 수 있습니다. 로그 뷰를 쿼리하면 스키마가 LogEntry 데이터 구조 스키마에 해당합니다. 분석 뷰 작성자가 스키마를 결정하므로 한 가지 분석 뷰 사용 사례는 로그 데이터를 LogEntry 형식에서 더 적합한 형식으로 변환하는 것입니다.

로그 애널리틱스는 로그 항목을 중복 삭제하지 않으므로 쿼리 작성 방법이 영향을 받을 수 있습니다. 또한 로그 애널리틱스를 사용할 때는 몇 가지 제한사항이 있습니다. 이러한 주제에 대한 자세한 내용은 다음 문서를 참조하세요.

연결된 데이터 세트 정보

로그 애널리틱스는 BigQuery가 기본 데이터에 대한 읽기 액세스 권한을 갖도록 연결된 BigQuery 데이터 세트 생성을 지원합니다. 연결된 데이터 세트를 만들면 다음을 수행하면 됩니다.

로그 항목 데이터를 다른 BigQuery 데이터 세트와 조인합니다.
BigQuery Studio 페이지 또는 Looker Studio와 같은 다른 서비스에서 로그 데이터를 쿼리합니다.
BigQuery 예약된 슬롯에서 쿼리를 실행하여 로그 애널리틱스에서 실행되는 쿼리의 성능을 향상시킵니다.
SQL 쿼리 결과를 모니터링하는 알림 정책을 만듭니다. 자세한 내용은 알림 정책으로 SQL 쿼리 결과 모니터링을 참조하세요.

이 문서에서는 연결된 데이터 세트를 만드는 방법이나 예약된 슬롯에서 쿼리를 실행하도록 로그 애널리틱스를 구성하는 방법을 설명하지 않습니다. 이러한 주제에 관심이 있으면 BigQuery에서 연결된 데이터 세트 쿼리를 참조하세요.

시작하기 전에

이 섹션에서는 로그 애널리틱스를 사용하려면 먼저 완료해야 하는 단계를 설명합니다.

로그 버킷 구성

로그 애널리틱스를 사용하도록 로그 버킷이 업그레이드되었는지 확인합니다.

Google Cloud 콘솔에서 로그 스토리지 페이지로 이동합니다.
로그 스토리지로 이동

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
쿼리하려는 로그 뷰가 있는 로그 버킷마다 로그 애널리틱스 사용 가능 열에 열기가 표시되어 있는지 확인합니다. 업그레이드가 표시되면 업그레이드를 클릭하고 대화상자를 완료합니다.

IAM 역할 및 권한 구성

이 섹션에서는 로그 애널리틱스를 사용하는 데 필요한 IAM 역할이나 권한을 설명합니다.

로그 애널리틱스를 사용하고 로그 뷰를 쿼리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
- _Required 및 _Default 로그 버킷을 쿼리하려는 경우: 로그 뷰어(roles/logging.viewer)
- 프로젝트의 모든 로그 뷰를 쿼리하려는 경우: 로그 뷰 접근자(roles/logging.viewAccessor)
프로젝트 수준에서 부여된 로그 뷰 액세스자 역할에 IAM 조건을 추가하거나 로그 뷰의 정책 파일에 IAM 바인딩을 추가하여 주 구성원을 특정 로그 뷰로 제한할 수 있습니다. 자세한 내용은 로그 뷰에 대한 액세스 제어를 참조하세요.

이는 로그 탐색기 페이지에서 로그 항목을 보는 데 필요한 권한과 같습니다. 사용자 정의 버킷에 대한 뷰를 쿼리하거나 _Default 로그 버킷의 _AllLogs 뷰를 쿼리하는 데 필요한 추가 역할에 대한 자세한 내용은 Cloud Logging 역할을 참조하세요.
분석 뷰를 쿼리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Observability Analytics 사용자(roles/observability.analyticsUser) IAM 역할을 부여해 달라고 요청하세요.

로그 데이터 쿼리

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

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

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

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
뷰 메뉴에서 로그 또는 분석 뷰 섹션으로 이동하여 쿼리할 뷰를 선택합니다.

쿼리할 뷰를 찾으려면 필터 막대를 사용하거나 목록을 스크롤합니다.
- 로그 뷰는 BUCKET_ID.LOG_VIEW_ID별로 나열되며 이러한 필드는 로그 버킷 및 로그 뷰의 ID를 참조합니다.
- 분석 뷰는 LOCATION.ANALYTICS_VIEW_ID별로 나열되며 이러한 필드는 분석 뷰의 위치와 ID를 참조합니다. 분석 뷰는 공개 프리뷰 버전입니다.
다음 중 하나를 수행합니다.
- 메뉴 선택으로 쿼리를 정의할 수 있는 쿼리 빌더를 사용하는 시스템 정의 쿼리를 로드하려면 쿼리 창에 쿼리 빌더가 표시되어 있는지 확인하세요. SQL 편집기가 표시되면 빌더를 클릭합니다.
- JSON 값을 추출하는 시스템 정의 쿼리를 로드하려면 쿼리 창에 SQL 편집기가 표시되어 있는지 확인합니다. 이 창에 쿼리 빌더가 표시되면 SQL을 클릭합니다.
스키마 창에서 쿼리를 선택한 다음 덮어쓰기를 클릭합니다.

쿼리 창에 시스템 정의 쿼리가 표시됩니다. 쿼리 빌더 모드를 선택했지만 SQL 쿼리를 보려면 SQL을 클릭합니다.
선택사항: 쿼리를 수정합니다.
쿼리를 실행하려면 툴바로 이동하여 쿼리 실행을 선택합니다.

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

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

맞춤 쿼리 입력 및 실행

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

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
쿼리 창에서 SQL을 클릭합니다.
- 기간을 지정하려면 기간 선택기를 사용하는 것이 좋습니다. timestamp 필드를 지정하는 WHERE 절을 추가하면 이 값이 기간 선택기의 설정을 재정의하고 해당 선택기는 사용 중지됩니다.
- 예시는 샘플 SQL 쿼리를 참고하세요.
- 로그 뷰 또는 분석 뷰를 쿼리할 수 있습니다. FROM 절에는 다음 형식을 사용합니다.
  - 로그 보기:
```
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
```
  - 애널리틱스 보기:
```
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`
```
  이전 표현식의 필드는 다음과 같은 의미를 갖습니다.
  - PROJECT_ID: 프로젝트 식별자
  - LOCATION: 로그 뷰 또는 분석 뷰의 위치
  - BUCKET_ID: 로그 버킷의 이름 또는 ID
  - LOG_VIEW_ID: 로그 뷰의 식별자로, 100자(영문 기준)로 제한되며 문자, 숫자, 밑줄, 하이픈만 포함할 수 있습니다.
  - ANALYTICS_VIEW_ID: 분석 뷰의 ID로, 100자(영문 기준)로 제한되며 문자, 숫자, 밑줄, 하이픈만 포함할 수 있습니다.
  쿼리 창에 FROM 문을 참조하는 오류 메시지가 표시되면 뷰를 찾을 수 없습니다. 이 실패를 해결하는 방법은 FROM 오류: 절에 정확히 하나의 로그 뷰가 포함되어야 함을 참고하세요.
쿼리를 실행하려면 툴바로 이동하여 쿼리 실행을 선택합니다.

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

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

쿼리 빌드, 수정, 실행

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

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

쿼리를 빌드하려면 다음을 수행합니다.

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
쿼리 창에 SQL 편집기가 표시되면 빌더를 선택합니다. 그러면 쿼리 빌더 창이 열립니다.
소스 메뉴를 사용하여 쿼리할 뷰를 선택합니다. 선택한 항목이 SQL 쿼리의 FROM 절에 매핑됩니다.
선택사항: 다음 메뉴를 사용하여 결과 표를 제한하거나 서식을 지정합니다.
- 모든 필드 검색: 일치하는 문자열을 검색합니다. 선택한 항목은 SQL 쿼리의 WHERE 절에 매핑됩니다.
- 열: 결과 표에 표시할 열을 선택합니다. 선택한 항목이 SQL 쿼리의 SELECT 절에 매핑됩니다.
  
  이 메뉴에서 필드 이름을 선택하면 대화상자가 열립니다. 이 대화상자에서 다음 작업을 할 수 있습니다.
  - 메뉴를 사용하여 데이터를 집계하거나 그룹화합니다.
    
    구문 오류를 방지하기 위해 한 열에 적용하는 집계 및 그룹화는 다른 열에도 자동으로 적용됩니다. 항목을 집계하고 그룹화하는 방법의 예는 쿼리 빌더를 사용하여 데이터 그룹화 및 집계를 참고하세요.
  - 모든 유형의 값을 지정된 다른 데이터 유형으로 변환합니다. 자세한 내용은 CAST 문서를 참고하세요.
  - 정규 표현식을 사용하여 값의 하위 문자열을 추출합니다. 자세한 내용은 REGEXP_EXTRACT 문서를 참고하세요.
- 필터: 특정 속성 또는 스팬 ID를 포함하는 스팬으로 쿼리를 제한하려는 경우 필터를 추가합니다. 메뉴에 사용 가능한 모든 필터 옵션이 표시됩니다. 선택한 항목은 SQL 쿼리의 WHERE 절에 매핑됩니다.
- 정렬 기준: 정렬할 열과 정렬이 오름차순인지 내림차순인지 설정합니다. 선택한 항목은 SQL 쿼리의 ORDER BY 절에 매핑됩니다.
- 한도: 결과 테이블의 최대 행 수를 설정합니다. 선택한 항목은 SQL 쿼리의 LIMIT 절에 매핑됩니다.
쿼리를 실행하려면 툴바로 이동하여 쿼리 실행을 선택합니다.

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

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

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

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

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

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

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

이 예에서는 쿼리 빌더를 사용하여 심각도 및 타임스탬프별로 로그 항목을 그룹화한 다음 각 그룹의 http_request.response_size 필드의 평균을 계산하는 방법을 설명합니다.

데이터를 그룹화하고 집계하는 쿼리를 빌드하려면 쿼리 빌더 메뉴에서 다음을 선택합니다.

열 메뉴에서 timestamp, severity, http_request.response_size 필드를 선택합니다.
1. 데이터를 그룹화하려면 timestamp 필드를 클릭하여 설정 대화상자를 엽니다. 이 대화상자에서 그룹화 기준 옵션을 선택하고 잘림 세부사항을 HOUR로 설정합니다. 그런 다음 구문 오류를 방지하기 위해 그룹화가 다른 모든 필드에 자동으로 적용됩니다. 그룹화를 적용할 수 없는 잘못된 필드가 있으면 오류 메시지가 표시됩니다. 이 오류를 해결하려면 메뉴에서 잘못된 필드를 삭제하세요.
2. http_request.response_size 필드에서 집계를 실행하려면 필드를 클릭하여 설정 대화상자를 엽니다. 이 대화상자에서 집계를 선택합니다. 집계 메뉴에서 평균을 클릭합니다.
  
  참고: 집계 옵션을 선택하면 열에 그룹화도 자동으로 적용됩니다.
필터 메뉴에서 http_request.response_size를 추가하고 비교 연산자를 IS NOT NULL로 설정합니다. 이 필터는 response_size 값이 포함된 로그 항목과 일치합니다.

쿼리 빌더 메뉴는 다음과 비슷하게 표시됩니다.

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

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

+-----------------------------------+----------+---------------+
| Row | hour_timestamp              | severity | response_size |
|     | TIMESTAMP                   | STRING   | INTEGER       |
+-----+-----------------------------+----------+---------------+
| 1   | 2025-10-06 16:00:00.000 UTC | NOTICE   | 3082          |
| 2   | 2025-10-06 17:00:00.000 UTC | WARNING  | 338           |
| 3   | 2025-10-06 16:00:00.000 UTC | INFO     | 149           |

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

SELECT
  -- Truncate the timestamp by hour.
  TIMESTAMP_TRUNC( timestamp, HOUR ) AS hour_timestamp,
  severity,
  -- Compute average response_size.
  AVG( http_request.response_size ) AS average_http_request_response_size
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries that have a response_size.
  http_request.response_size IS NOT NULL
GROUP BY
  -- Group log entries by timestamp and severity.
  TIMESTAMP_TRUNC( timestamp, HOUR ),
  severity
LIMIT
  1000

스키마 표시

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

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

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
뷰 메뉴에서 로그 또는 분석 뷰 섹션으로 이동하여 쿼리할 뷰를 선택합니다.

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

로그 뷰의 경우 스키마가 고정되어 있으며 LogEntry에 해당합니다. 분석 뷰의 경우 SQL 쿼리를 수정하여 스키마를 변경할 수 있습니다.