Logging 쿼리 언어를 사용하여 쿼리 빌드 및 저장

이 문서에서는 쿼리 편집기 필드에 쿼리를 작성하고 로그 항목에 포함된 옵션을 사용해 필터 메뉴에서 선택하여 로그 탐색기를 사용할 때 로그를 검색하고 분석하는 방법에 대해 설명합니다. 빌드한 쿼리는 Logging 쿼리 언어로 작성됩니다.

로그 탐색기 페이지에 쿼리를 저장하거나 Logging API 메서드 savedQueries.create를 사용하여 쿼리를 저장할 수도 있습니다.

시작하기 전에

로그 데이터를 읽고 쿼리를 빌드하거나, 비공개 저장된 쿼리를 사용하거나, 공유 쿼리를 나열하고 가져오는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 로그 뷰어(roles/logging.viewer) IAM 역할을 부여해 달라고 요청하세요.

이 사전 정의된 역할에는 로그 데이터를 읽어 쿼리를 빌드하거나, 비공개 저장된 쿼리를 사용하거나, 공유 쿼리를 나열하고 가져오는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한

로그 데이터를 읽어 쿼리를 빌드하거나, 비공개로 저장된 쿼리를 사용하거나, 공유 쿼리를 나열하고 가져오려면 다음 권한이 필요합니다.
- 비공개 저장된 쿼리 사용: logging.queries.usePrivate
- 공유 쿼리 나열 및 가져오기:
  - logging.queries.listShared
  - logging.queries.getShared

공유 쿼리를 생성, 업데이트, 삭제하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Logging 관리자(roles/logging.admin) IAM 역할을 부여해 달라고 요청하세요.

이 사전 정의된 역할에는 공유 쿼리를 만들고, 업데이트하고, 삭제하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한

공유 쿼리를 만들고, 업데이트하고, 삭제하려면 다음 권한이 필요합니다.
- logging.queries.share
- logging.queries.updateShared
- logging.queries.deleteShared

필요한 IAM 권한에 대한 자세한 내용은 Google Cloud 콘솔 권한을 참고하세요.

쿼리 빌드

Google Cloud 콘솔을 사용하여 쿼리를 빌드하려면 다음을 수행합니다.

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
Google Cloud 프로젝트 또는 로그를 확인하려는 다른 Google Cloud 리소스를 선택합니다.
쿼리 창을 사용하여 쿼리를 빌드합니다.

쿼리 창에서는 여러 방법으로 쿼리 표현식을 빌드하고 실행할 수 있습니다.
- 모든 로그 필드에서 텍스트를 검색합니다.
- 필터 메뉴에서 옵션을 선택합니다.
- 쿼리 편집기를 사용하여 쿼리를 작성하거나 수정합니다.
- 쿼리 라이브러리에서 저장된 쿼리, 최근 쿼리, 추천 쿼리를 보고 실행합니다.

로그 필드에서 텍스트 검색

모든 로그 필드에서 텍스트를 검색하고 일치하는 모든 로그 항목을 찾으려면 검색 창의 검색창에 검색어를 입력합니다.

단어와 구문을 검색할 수 있으며 검색어에 불리언 연산자 및 정규 표현식을 포함할 수 있습니다.

대소문자를 구분하는 검색을 수행하려면 정규 표현식을 사용해야 합니다.
토큰 경계를 따라 대소문자를 구분하지 않는 검색을 수행하려면 백틱 또는 큰따옴표 없이 검색어를 입력합니다.

예를 들어 hello라는 단어와 world라는 단어가 포함된 로그 항목을 검색하려면 hello world를 입력합니다. SEARCH("hello world")로 변환되는 이 명령어는 hello 및 world 토큰을 포함하는 로그 항목과 어떤 순서로든 일치합니다. 검색 시 대소문자를 구분하지 않으므로 검색은 Hello 및 World 토큰이 포함된 로그 항목과도 일치합니다. 이 검색은 worlds 토큰과 일치하지 않습니다.
토큰 경계를 따라 구문 검색 시 대소문자를 구분하지 않으려면 구문을 백틱으로 묶습니다.

예를 들어 hello world 구문을 검색하려면 `hello world`를 입력합니다. SEARCH("`hello world`")로 변환되는 이 명령어는 hello world 토큰을 포함하는 로그 항목과 일치합니다. 이 검색은 hello worlds 토큰과 일치하지 않습니다.
하위 문자열에 대해 대소문자를 구분하지 않는 검색을 수행하려면 텍스트를 큰따옴표로 묶습니다. 예를 들어 "hello world"는 Hello World 및 Hello world와 일치합니다. 검색이 토큰 경계를 따라 수행되지 않으므로 동일한 쿼리도 hello worlds와 일치합니다.

참고: 하위 문자열 검색은 토큰 기반 검색보다 느립니다. 따라서 가능하면 토큰 기반 검색을 사용하는 것이 좋습니다.

쿼리 표현식 내에서 검색어를 보려면 쿼리 표시를 사용 설정합니다.

검색어를 입력한 후 쿼리 실행을 클릭하거나 Enter 키를 누릅니다. 쿼리 결과가 쿼리 결과 창에 표시됩니다.

불리언 연산자

검색 필드 항목은 선택된 Google Cloud 리소스에 있는 모든 로그 항목의 하위 집합을 지정하는 불리언 표현식으로 변환됩니다.

검색 필드에서 불리언 연산자 AND, OR, NOT을 사용할 수 있습니다. 검색 표현식에서 불리언 연산자를 사용할 때는 다음 사항에 유의하세요.

규칙을 중첩하는 데 괄호를 사용할 수 없습니다. 검색 표현식의 괄호는 검색어로 파싱됩니다.
불리언 연산자를 대문자로 표기해야 합니다. 소문자 and, or, not은 연산자가 아닌 검색어로 파싱됩니다.

연산자를 포함하지 않으면 모든 검색어와 구문이 AND로 연결됩니다. 검색어 사이에 AND 연산자를 생략할 수 있습니다.

AND 및 OR 연산자는 단락 연산자입니다. 같은 표현식에서 AND 규칙과 OR 규칙을 결합할 수 있습니다. 예를 들어 두 연산자가 혼합되면 a AND b OR c AND d 표현식은 다음 Logging 쿼리 언어 표현식으로 변환됩니다.

"a"
"b" OR "c"
"d"

NOT 연산자의 우선순위가 가장 높고 그 다음으로 OR와 AND의 순입니다.

NOT 연산자는 후속 항의 부정을 수행합니다. 예를 들어 NOT error는 error가 포함되지 않은 로그 항목을 반환합니다. NOT 연산자를 -(빼기) 연산자로 바꿀 수도 있습니다. 예를 들어 다음 두 쿼리는 동일합니다.

"response" AND "successful" AND NOT "error"

"response successful" -"error"

-(빼기) 연산자가 따옴표 밖에 있으면 이 논리가 구문에서도 작동합니다. 예를 들어 다음 두 쿼리는 동일합니다.

-"response successful"

NOT "response successful"

필터 메뉴로 쿼리 작성

쿼리 창의 필터 메뉴를 사용하여 쿼리 편집기 필드에 리소스, 로그 이름, 로그 심각도, 상관 매개변수를 추가할 수 있습니다. 이러한 옵션은 Logging의 모든 로그에 대한 LogEntry 필드에 해당합니다.

The options in the 리소스 및 로그 이름 메뉴의 옵션은 Cloud Logging에 저장된 로그 항목에서 파생됩니다.

리소스: resource.type 및 연결된 resource.labels를 지정할 수 있습니다. 이 필터 메뉴를 사용하여 단일 리소스 유형과 쿼리를 적용할 리소스 라벨을 0개 이상 선택할 수 있습니다. 리소스 매개변수는 논리 연산자 AND에 의해 조인됩니다.
로그 이름: logName을 지정할 수 있습니다. 여러 로그 이름을 선택하여 쿼리에 적용할 수 있습니다. 로그 이름을 여러 개 선택하면 논리 연산자 OR이 사용됩니다.
심각도: 심각도를 지정할 수 있습니다. 심각도 수준 여러 개를 동시에 선택하여 쿼리에 추가해 적용할 수 있습니다. 심각도 수준을 여러 개 선택할 때 논리 연산자 OR을 사용합니다.
상관관계 분석: 로그 항목을 '상위-하위' 형식으로 그룹화하고 볼 수 있습니다. 자세한 내용은 로그 항목 상관 분석을 참고하세요.

필터 메뉴를 사용하려면 다음을 수행합니다.

쿼리 창의 필터 메뉴에서 메뉴를 펼칩니다.
필터 매개변수를 상세검색합니다.
적용을 클릭합니다. 쿼리 편집기 필드에 매개변수가 표시됩니다.

쿼리 표현식 내에서 검색어를 보려면 쿼리 표시를 사용 설정합니다.
쿼리를 검토한 후 쿼리 실행을 클릭합니다. 쿼리 결과가 쿼리 결과 창에 표시됩니다.

gce_instance 및 gce_network와 같은 특정 Compute Engine 리소스 유형의 경우 리소스 ID가 하위 텍스트로 포함된 리소스 이름이 표시됩니다. 예를 들어 gce_instance 리소스 유형은 VM ID와 함께 VM 이름이 표시됩니다. 리소스 이름은 쿼리를 빌드할 수 있는 올바른 리소스 ID를 식별하는 데 도움이 됩니다.

시간 범위별 로그 보기

특정 기간에 작성된 로그를 표시하는 방법에는 두 가지가 있습니다.

시간 범위 선택기 사용
쿼리 편집기 필드에 타임스탬프 표현식 포함

시간 범위 선택기 사용

기본 시간 범위는 1시간이지만 사전 설정 시간 옵션에서 선택하거나, 커스텀 시작 및 종료 시간을 지정하거나, 시간 범위 선택기를 사용하여 특정 타임스탬프를 중심으로 시간 범위를 정할 수 있습니다. 예를 들어 지난주의 데이터를 보려면 시간 범위 선택기에서 지난 1주를 선택합니다.

시간 범위 선택기를 사용하여 시간대 환경설정을 지정할 수도 있습니다.

쿼리 편집기 필드에 타임스탬프 표현식 포함

타임스탬프 표현식을 쿼리 편집기 필드에 직접 추가하려면 Logging 쿼리 언어를 사용합니다.

쿼리 편집기 필드에 타임스탬프가 있는 표현식이 포함된 경우 시간 범위 선택기가 사용 중지되고 쿼리에서 타임스탬프 표현식을 시간 범위 제한으로 사용합니다. 쿼리에서 타임스탬프 표현식을 사용하지 않는 경우 쿼리는 시간 범위 선택기를 시간 범위 제한으로 사용합니다.

Logging 쿼리 언어를 사용하여 고급 쿼리 작성

Logging 쿼리 언어를 사용하여 로그 탐색기 쿼리 편집기 필드에서 고급 쿼리를 빌드할 수 있습니다.

쿼리 창에 쿼리 편집기 필드가 표시되지 않으면 쿼리 표시를 사용 설정합니다.
쿼리 표현식을 쿼리 편집기 필드에 직접 입력합니다.

검색 필드에 검색어를 추가하거나 필터 메뉴에서 매개변수를 선택한 경우 쿼리 편집기 필드에도 이러한 쿼리가 표시되며 쿼리 표현식의 일부로 평가됩니다.
쿼리를 검토한 후 쿼리 실행을 클릭합니다.

쿼리와 일치하는 로그가 쿼리 결과 창에 나열됩니다. 히스토그램 창과 로그 필드 창도 쿼리 표현식에 따라 조정됩니다.

사용하려는 일반적인 쿼리의 예시는 로그 탐색기를 사용하는 샘플 쿼리를 참조하세요.

최근 쿼리 사용

쿼리를 실행하면 쿼리가 쿼리 라이브러리에 추가되는데, 라이브러리에는 30일 동안 발생한 10,000개의 고유한 쿼리가 보관됩니다.

최근 쿼리를 보려면 기본 툴바에서 쿼리 라이브러리 버튼을 선택합니다. 최근 검색어의 경우 다음과 같은 옵션이 있습니다.

스트림: 쿼리를 실행하고 결과를 스트림하려면 이 옵션을 선택합니다.
실행: 쿼리를 실행하려면 이 옵션을 선택합니다.
추가 옵션: 쿼리 실행 옵션과 함께 쿼리 표현식을 보거나 저장된 쿼리 목록에 저장할 수 있습니다. 쿼리를 직접 선택하여 이러한 옵션을 가져올 수도 있습니다.

쿼리를 저장하려면 다음을 수행합니다.
1. 저장을 클릭합니다. 쿼리 저장 대화상자가 열립니다.
2. 다음 입력란을 작성하세요.
  - 이름(필수): 쿼리 이름을 입력합니다. 이름은 64자로 제한됩니다.
  - 설명(선택사항): 쿼리의 목적을 식별하는 데 도움이 되는 설명을 제공합니다.
  - 요약 필드 포함(선택사항): 요약 필드 포함을 사용 설정하고 표시할 요약 필드를 입력합니다.
  - 요약 필드 자르기(선택사항): 요약 필드 자르기를 사용 설정하고 잘라낼 문자 수와 자르기가 필드의 시작 부분에서 발생할지 끝부분에서 발생할지 여부를 선택합니다.
3. 쿼리 저장을 클릭합니다. 이제 저장된 쿼리 목록에서 쿼리를 사용할 수 있습니다.

최근 쿼리를 정렬하고 필터링할 수도 있습니다. 필터는 쿼리 표현식에 있는 텍스트와 일치합니다.

쿼리 저장 및 공유

저장된 쿼리를 사용하면 쿼리 표현식을 저장하여 로그를 일관되고 효율적으로 탐색할 수 있습니다. 로그 탐색기에는 저장된 쿼리에 액세스할 수 있는 쿼리 라이브러리가 있습니다. 또한, Logging API 메서드 savedQueries.create를 사용하여 쿼리를 저장할 수도 있습니다.

비공개 및 본인만 볼 수 있도록 쿼리를 저장하거나 Google Cloud 프로젝트의 다른 구성원과 공유할 수 있습니다. 쿼리를 공유하면 쿼리는 더 이상 사용자의 소유가 아니며 필요한 권한이 있는 프로젝트의 모든 구성원이 쿼리에 액세스할 수 있습니다.

콘솔

쿼리 편집기 필드에서 빌드한 쿼리 표현식을 저장하려면 다음을 수행합니다.

쿼리 창에서 저장을 클릭합니다. 쿼리 저장 대화상자가 열리고 쿼리 편집기 필드에 쿼리 표현식이 표시됩니다.
다음 입력란을 작성하세요.
- 이름(필수): 쿼리 이름을 입력합니다. 이름은 64자로 제한됩니다.
- 설명(선택사항): 쿼리의 목적을 식별하는 데 도움이 되는 설명을 제공합니다.
- 커스텀 요약 필드 포함(선택사항): 요약 필드 포함을 사용 설정하고 표시할 요약 필드를 입력합니다.
- 요약 필드 자르기(선택사항): 요약 필드 자르기를 사용 설정하고 잘라낼 문자 수와 자르기가 필드의 시작 부분에서 발생할지 끝부분에서 발생할지 여부를 선택합니다.
- 프로젝트와 공유: 원하는 경우 프로젝트와 공유를 사용 설정하여 Google Cloud 프로젝트의 다른 구성원과 쿼리를 공유합니다.
쿼리 저장을 클릭합니다. 저장된 쿼리는 저장됨 탭의 목록에 나타납니다.

저장된 쿼리를 실행하려면 실행을 클릭합니다. 쿼리를 실행하고 결과를 스트림하려면 스트림을 클릭합니다.

저장된 쿼리를 수정하려면 옵션 더보기를 선택한 다음 수정을 선택합니다. 쿼리를 선택하고 수정한 후 수정된 쿼리를 저장할 수도 있습니다.

저장된 쿼리를 삭제하려면 옵션 더보기를 선택한 다음 삭제를 선택합니다.

저장된 쿼리를 정렬하고 필터링할 수도 있습니다. 필터는 쿼리 표현식에 있는 텍스트와 일치합니다.

API

Logging API를 사용하여 쿼리를 저장하려면 savedQueries.create 메서드를 사용하세요. 이 메서드, 매개변수, 응답 데이터에 대한 상세 정보는 savedQueries.create를 위한 참조 페이지를 확인하세요.

savedQueries.create 메서드의 참조 페이지에서 API 탐색기 위젯을 사용하여 해당 메서드를 실행할 수 있습니다. 로그 탐색기 쿼리의 경우에는 loggingQuery 필드를 지정해야 합니다. 다음 예시에서는 SavedQuery 인스턴스가 포함된 샘플 요청 본문을 보여줍니다.

{
  "parent": "projects/my-project/locations/global"
  "savedQueryId": "compute-query"
  {
    "displayName": "compute-admin-activity-query",
    "description": "Queries for Compute Engine Admin Activity logs.",

    "loggingQuery":
      {
        "filter": resource.type="gce_instance" AND log_id("cloudaudit.googleapis.com/activity"),
      },
    "visibility": "PRIVATE"
  }
}

Google Cloud 프로젝트의 다른 구성원과 쿼리를 공유하려면 visibility 필드에 SHARED 값을 지정합니다.

저장된 쿼리 보기

쿼리 라이브러리 버튼을 클릭하면 비공개 쿼리와 Google Cloud 프로젝트의 다른 멤버와 공유된 쿼리를 모두 볼 수 있습니다.

콘솔

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
Google Cloud 프로젝트 또는 로그를 확인하려는 다른 Google Cloud 리소스를 선택합니다.
쿼리 라이브러리 버튼을 클릭하고 저장됨을 클릭합니다.

표를 헤더별로 정렬할 수 있습니다. 공개 상태 열은 쿼리가 공유되는지 또는 비공개인지를 나타냅니다.

공유됨: Google Cloud 프로젝트의 다른 구성원과 공유된 쿼리입니다.
비공개: 저장하고 나에게만 표시되는 쿼리입니다.

API

Logging API를 사용하면 savedQueries.list 메서드를 사용하여 비공개 및 공유 쿼리를 볼 수 있습니다.

예를 들어 다음 요청 본문은 와일드 카드 위치 ID가 있는 모든 공유 로그 탐색기 쿼리를 나열합니다.

{
  "parent": "name": projects/PROJECT_ID/locations/-
  "visibility": "SHARED"
  "filter": "explorer"
}

라이브러리에서 쿼리 선택

Logging은 일반적인 사용 사례와 Google Cloud 제품을 기반으로 하는 쿼리 라이브러리를 제공합니다. 이러한 쿼리는 시간이 중요한 문제 해결 세션 중에 로그를 효율적으로 찾고 로그를 탐색하여 사용 가능한 Logging 데이터를 더욱 효율적으로 파악하는 데 도움이 됩니다.

라이브러리의 쿼리를 보고 실행하려면 다음을 수행합니다.

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
Google Cloud 프로젝트 또는 로그를 확인하려는 다른 Google Cloud 리소스를 선택합니다.
라이브러리 쿼리 버튼을 클릭합니다. Google Cloud 제품을 기반으로 사용 가능한 쿼리 카테고리와 쿼리 하위 집합이 표시됩니다. 표시되는 쿼리 선택 범위를 좁히려면 제품을 클릭합니다.

검색 필드를 사용하여 카테고리, 설명 또는 쿼리 표현식의 콘텐츠로 사용 가능한 쿼리를 검색할 수도 있습니다.
쿼리 표현식을 검토하려면 다음 중 하나를 수행합니다.

a. 쿼리 행을 클릭합니다.

b. 더보기를 클릭하고 보기를 선택합니다.
쿼리 세부정보 대화상자에 쿼리와 실행, 스트림 또는 다른 이름으로 저장 옵션이 표시됩니다.
- 쿼리를 저장하려면 다음을 수행합니다.
  1. 쿼리 저장을 클릭합니다.
  2. 쿼리 저장 대화상자 필드를 작성합니다.
  저장됨 목록에 수정된 쿼리가 표시됩니다. 여기에서 나중에 쿼리를 실행하도록 선택할 수 있습니다.
- 지금 쿼리를 실행하려면 실행을 클릭합니다. 쿼리가 실행되고 쿼리 편집기 필드에 표시됩니다.
- 지금 쿼리를 실행하고 결과를 스트림하려면 스트림을 클릭합니다.
- 대화상자를 닫고 추천 쿼리 목록으로 돌아가려면 닫기를 클릭합니다.

다음 단계

샘플 쿼리