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

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

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

시작하기 전에

쿼리를 빌드하려면 로그 데이터를 읽을 수 있는 권한이 있어야 합니다. 이러한 권한은 Logging 뷰어(roles/logging.viewer) 역할에 포함되어 있습니다. 필요한 IAM 권한에 대한 자세한 내용은 Google Cloud 콘솔 권한을 참조하세요.
쿼리를 저장하려면 Identity and Access Management 역할에 logging.queries.{list, create, get, update, delete} 권한이 포함되어야 합니다.
쿼리를 공유하려면 Identity and Access Management 역할에 logging.queries.share 권한이 포함되어야 합니다. 이 권한은 소유자(roles/owner) 및 Logging 관리자(roles/logging.admin) 역할에 포함되어 있습니다.

각 Logging 역할과 연결된 권한 목록은 Logging 역할을 참조하세요.

쿼리 빌드

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

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
Google Cloud 프로젝트 또는 로그를 확인하려는 다른 Google Cloud 리소스를 선택합니다.
Amazon Web Services(AWS) 계정에서 Logging으로 전송하는 로그를 보려면 Google Cloud 콘솔 리소스 선택도구에서 AWS 커넥터 프로젝트를 선택한 다음 로그 탐색기를 사용합니다. AWS 커넥터 프로젝트는 AWS 계정의 Amazon 리소스 이름(ARN)을 저장하고 AWS 계정을 Google Cloud 서비스에 연결합니다. 자세한 내용은 AWS 계정에서 측정항목 수집을 참조하세요.
쿼리 창을 사용하여 쿼리를 빌드합니다.

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

로그 필드에서 텍스트 검색

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

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

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

예를 들어 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에 의해 조인됩니다.
로그 이름: 로그 이름을 지정할 수 있습니다. 여러 로그 이름을 선택하여 쿼리에 적용할 수 있습니다. 로그 이름을 여러 개 선택하면 논리 연산자 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를 사용하여 쿼리를 저장할 수도 있습니다.

콘솔

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

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

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

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

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 프로젝트 사용자가 저장된 쿼리를 서로 공유할 수 있습니다. 저장됨 탭에서 공유 쿼리를 볼 수 있습니다.

공유 쿼리를 보고 수정하는 데 필요한 역할 및 권한은 Google Cloud 콘솔 권한을 참조하세요. roles/logging.admin 또는 roles/editor IAM 역할을 가진 사용자는 다른 사용자의 공유 쿼리를 수정할 수 있습니다.

콘솔

이미 저장한 쿼리를 공유하거나 새 쿼리를 공유할 수 있습니다.

쿼리를 만들고 공유하려면 다음을 수행합니다.

쿼리 편집기 필드에 쿼리를 입력합니다.
저장을 클릭합니다.
쿼리 저장 대화상자 필드를 작성합니다.
프로젝트와 공유를 사용 설정합니다.
쿼리 저장을 클릭합니다.

이제 쿼리가 Google Cloud 프로젝트의 다른 사용자와 공유됩니다.

이미 저장된 쿼리를 공유하려면 다음 안내를 따르세요.

저장됨 탭을 선택합니다.
옵션 더보기를 선택한 다음 수정을 선택하거나 쿼리를 직접 선택합니다.
쿼리 수정 대화상자에서 프로젝트와 공유를 사용 설정한 후 쿼리 업데이트를 클릭합니다.

이제 쿼리가 Google Cloud 프로젝트의 다른 사용자와 공유됩니다.

API

Logging API를 이용하면 savedQueries.Create 메서드를 사용하고 visibility 필드에 SHARED 값을 지정하여 공유 쿼리를 만들 수 있습니다.

공유 쿼리 보기

콘솔

모든 공유 쿼리를 빠르게 보려면 공개 상태 열을 정렬하여 공유 쿼리를 먼저 표시합니다.

저장됨 탭을 선택합니다.
전체를 클릭합니다.
공개 상태 열을 정렬합니다.

공개 상태 열은 쿼리가 공유되는지 여부와 방법을 나타냅니다.

내가 공유한 쿼리: 저장하고 Google Cloud 프로젝트의 다른 사용자와 공유한 쿼리입니다.
공유: Google Cloud 프로젝트의 다른 사용자가 공유한 쿼리입니다.
비공개: 저장하고 Google Cloud 프로젝트의 다른 사용자와 공유하지 않은 쿼리입니다.

쿼리만 보기

내가 만들거나 공유한 저장된 쿼리를 보려면 내 쿼리를 클릭합니다. 이제 만들고 저장한 쿼리 목록이 표시됩니다. 공개 상태 열에서 공유되지 않은 비공개 쿼리를 볼 수 있습니다. 공유한 쿼리는 내가 공유한 쿼리로 표시됩니다.

라이브러리에서 쿼리 선택

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

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

쿼리 창에서 라이브러리 탭을 선택합니다.
모든 쿼리 열에 Google Cloud 제품을 기반으로 사용 가능한 쿼리와 쿼리 하위 집합의 다양한 카테고리가 표시됩니다. 표시되는 쿼리 선택 범위를 좁히려면 제품을 클릭합니다.

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

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

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

다음 단계

샘플 쿼리