고급 로그 쿼리

이 가이드에서는 기존 로그 뷰어를 사용하여 로그 개수에 관계없이 로그에서 로그 항목 집합을 지정할 수 있는 표현식인 고급 로그 쿼리를 작성하는 방법을 설명합니다. 고급 로그 쿼리는 기존 로그 뷰어 ,Logging API 또는 gcloud 명령줄 도구에서 사용할 수 있습니다.

기본 쿼리 옵션에 대한 자세한 내용은 기본 로그 쿼리를 참조하세요.

로그의 추천 쿼리 목록은 샘플 쿼리를 참조하세요.

소개

고급 로그 쿼리는 프로젝트의 모든 로그 항목 하위 집합을 지정하는 부울 표현식입니다. 이 쿼리를 사용하여 다음과 같은 작업을 모두 수행할 수 있습니다.

  • 특정 로그 또는 로그 서비스에서 로그 항목을 선택합니다.
  • 특정 시간 범위에 있는 로그 항목을 선택합니다.
  • 메타데이터 또는 사용자 정의 필드의 조건을 충족하는 로그 항목을 선택합니다.
  • 모든 로그 항목의 샘플링 비율을 선택합니다.

고급 로그 쿼리 시작하기

로그 뷰어에서 고급 로그 쿼리를 사용하려면 다음 안내를 따르세요.

  1. Cloud Console에서 Google Cloud 운영 제품군 로깅 > 로그 페이지로 이동합니다.

    기존 로그 뷰어 페이지로 이동

  2. 페이지 상단에서 기존 Google Cloud 프로젝트를 선택하거나 새 프로젝트를 만듭니다.

  3. 드롭다운 메뉴 를 사용하여 로그를 보려는 리소스를 선택합니다.

  4. 검색어 상자에서 드롭다운 메뉴 를 클릭하고 고급 필터로 전환을 선택합니다.

고급 필터 전환을 보여주는 사용자 인터페이스

로그 쿼리를 사용하면 특정 로그 항목 집합을 선택할 수 있으므로 사용자 인터페이스에서 로그 쿼리가 '필터'로 표시됩니다.

다음과 같은 고급 쿼리 인터페이스가 표시됩니다.

고급 필터 옵션을 보여주는 사용자 인터페이스

이 쿼리 인터페이스의 특징은 로그 선택 메뉴가 없고 필터 제출 버튼이 있다는 것입니다. 기존 로그 뷰어에는 쿼리에 지정된 모든 조건을 충족하는 로그 항목이 표시됩니다.

다음은 고급 로그 쿼리의 간단한 예시입니다.

    resource.type = "gce_instance" AND
    severity >= ERROR AND
    NOT textPayload:robot

이 쿼리는 Compute Engine의 로그 항목 중 심각도 값이 최소한 ERROR이고 textPayload 필드에 robot 문자열이 포함되지 않은 로그 항목을 걸러냅니다. 문자열 비교는 대소문자를 구분하지 않습니다. resource, severity, textPayload 이름은 LogEntry 유형에 정의되어 있습니다.

입력 시 제안 및 강조표시: 기존 로그 뷰어에 고급 로그 쿼리를 입력할 때 특정 로그 항목 필드에 대한 제안사항이 표시될 수 있습니다. 이러한 제안은 쿼리 언어와 기존 로그 뷰어가 로드한 실제 로그 항목 집합에 기초합니다. 제안을 선택하려면 TAB 키를 누릅니다. 제안이 표시되지 않으면 CTRL + SPACE 키를 누릅니다. 쿼리 표현식의 각 부분이 서로 다른 색상으로 강조표시됩니다. 표현식이 밝은 빨간색이면 지금까지 입력한 쿼리가 불완전하거나 오류가 있을 수 있습니다.

따옴표로 묶지 않은 텍스트: 공백이나 일부 특수문자가 포함되어 있지 않은 텍스트 문자열은 따옴표로 묶지 않아도 됩니다. 이를 따옴표로 묶지 않은 텍스트라고 하며, 앞의 예시에서의 ERRORrobot과 같은 단어를 예로 들 수 있습니다. 문자열 "v1.compute.instances.insert"는 마침표를 포함하고 있으므로 따옴표로 묶였습니다. 문자열 안에 따옴표를 포함시키려면 따옴표 앞에 백슬래시를 붙이세요.

권장사항: 필드 값과 비교하려는 문자열에 따옴표를 붙입니다. 이렇게 하면 실수로 비교의 의미가 바뀌어 디버깅하기가 어려워지는 일을 막을 수 있습니다. 한 문자 뒤에 문자, 숫자 또는 밑줄(_) 문자가 연달아 오는 단어에는 따옴표를 생략할 수 있습니다.

키보드 사용: 키보드를 사용하여 검색어 상자에 고급 로그 쿼리를 입력하는 경우 ESC 키를 눌러 수정 모드를 종료한 후 TAB 키를 눌러 드롭다운 메뉴 또는 필터 제출 버튼과 같은 다른 옵션으로 이동할 수 있습니다.

고급 로그 쿼리 구문

이 섹션에서는 고급 로그 쿼리의 구조와 일치 수행 방법을 설명합니다.

구문 표기법

고급 로그 쿼리 구문은 다음과 같은 표기법으로 표현됩니다.

  • a = ea가 표현식 e의 이름이라는 뜻입니다.
  • a b는 'a 다음에 b가 온다'는 뜻입니다.
  • a | b는 'a 또는 b'라는 뜻입니다.
  • ( e )는 그룹화에 사용됩니다.
  • [ e ]e가 선택사항이라는 뜻입니다.
  • { e }e를 0회 이상 반복할 수 있다는 뜻입니다.
  • 'abc'는 abc를 보이는 그대로 작성해야 한다는 뜻입니다.

구문 요약

   expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }

비교는 단일 값 또는 부울 표현식입니다.

  "The cat in the hat"
  resource.type = "gae_app"

첫 번째 줄은 단일 값인 비교의 예시입니다. 이러한 유형의 비교는 전역 제한입니다. has 연산자를 암시적으로 사용하여 로그 항목의 각 필드를 값과 비교합니다. 이 예시에서 LogEntry의 필드 또는 페이로드에 'The cat in the hat'이라는 구문이 있으면 비교가 성공한 것입니다.

두 번째 줄은 [FIELD_NAME] [OP] [VALUE] 형식의 부울 표현식인 비교의 예시입니다. 비교 요소는 아래에 설명되어 있습니다.

  • [FIELD_NAME]: 로그 항목의 필드입니다. 예를 들면 resource.type입니다.

  • [OP]: 비교 연산자입니다. 예를 들면 =입니다.

  • [VALUE]: 숫자, 문자열, 함수 또는 괄호로 묶은 표현식입니다. 예를 들면 "gae_app"입니다.

쿼리와 일치에 관해서는 다음 섹션에서 더 자세히 다룹니다.

부울 연산자

부울 연산자 ANDOR단락 연산자입니다. NOT 연산자의 우선순위가 가장 높고 그 다음으로 ORAND의 순입니다. 예를 들어 다음 두 연산자는 서로 동일합니다.

a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)

비교 사이에 AND 연산자를 생략할 수 있습니다. NOT 연산자를 -(빼기) 연산자로 바꿀 수도 있습니다. 예를 들어 다음 두 쿼리는 동일합니다.

a=b AND c=d AND NOT e=f
a=b c=d -e=f

이 문서는 항상 ANDNOT을 사용합니다.

비교

비교 형식은 다음과 같습니다.

[FIELD_NAME] [OP] [VALUE]

비교 요소는 아래에 설명되어 있습니다.

  • [FIELD_NAME]: 로그 항목의 필드 경로 이름입니다. 필드 이름의 예시는 다음과 같습니다.

    resource.type
    resource.labels.zone
    resource.labels.project_id
    insertId
    jsonPayload.httpRequest.protocol
    labels."compute.googleapis.com/resource_id"
    

    경로 이름 구성요소에 특수문자가 있으면 경로 이름을 큰따옴표로 묶어야 합니다. 예를 들어 compute.googleapis.com/resource_id는 슬래시 /가 포함되어 있으므로 이 이름을 큰따옴표로 묶어야 합니다.

    자세한 내용은 이 페이지의 필드 경로 식별자를 참조하세요.

  • [OP]: 비교 연산자이며 다음 중 하나입니다

    =           # equal
    !=          # not equal
    > < >= <=   # numeric ordering
    :           # "has" matches any substring in the log entry field
    =~          # regular expression search for a pattern
    !~          # regular expression search not for a pattern
    
  • [VALUE]: 숫자, 문자열, 함수 또는 괄호로 묶은 표현식입니다. 문자열은 임의의 텍스트와 부울, 열거형, 바이트 문자열 값을 나타내는 데 사용됩니다. [VALUE]는 비교하기 전에 필드 유형으로 변환됩니다.

[VALUE]가 여러 비교 값의 부울 조합을 괄호로 묶은 형태인 경우 각 요소에 필드 이름과 비교 연산자가 적용됩니다. 예를 들면 다음과 같습니다.

    jsonPayload.cat = ("longhair" OR "shorthair")
    jsonPayload.animal : ("nice" AND "pet")

첫 번째 비교에서는 cat 필드 값이 'longhair' 또는 'shorthair'인지 확인합니다. 두 번째 비교에서는 animal 필드 값에 'nice'와 'pet' 단어가 순서에 관계없이 모두 포함되어 있는지 확인합니다.

필드 경로 식별자

모든 로그 항목은 LogEntry 유형의 인스턴스입니다. 비교의 왼쪽에 있는 식별자나 왼쪽의 시작 부분이 되는 식별자는 LogEntry 유형으로 정의된 필드여야 합니다. 사용 가능한 식별자와 그 값에 관한 자세한 내용은 LogEntry 유형을 참조하세요.

로그 항목 필드의 현재 목록은 다음과 같습니다. 각 필드 다음에는 그 필드의 다음 수준 이름이 따라옵니다(해당되는 경우).

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status, userAgent }
  • insertId
  • jsonPayload { 변수 }
  • labels { 변수 }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, 변수 }
  • receiveTimestamp
  • resource { type, labels }
  • severity
  • sourceLocation: { file, line, function }
  • spanId
  • textPayload
  • timestamp
  • trace

비교에 사용할 수 있는 필드 경로 식별자의 예를 들면 다음과 같습니다.

  • resource.type: 첫 번째 경로 식별자가 resource이면 다음 식별자는 MonitoredResource 유형의 필드여야 합니다.

  • httpRequest.latency: 첫 번째 경로 식별자가 httpRequest이면 다음 식별자는 HttpRequest 유형의 필드여야 합니다.

  • labels.[KEY]: 첫 번째 경로 식별자가 labels이면 다음 식별자인 [KEY]labels 필드에 표시되는 키-값 쌍의 키 중 하나여야 합니다.

  • logName: logName 필드는 문자열이므로 다음에 어떠한 하위 필드 이름도 올 수 없습니다.

특수문자

LogEntry 필드에 특수문자가 있으면 로그 필드를 따옴표로 묶어야 합니다. 예를 들면 다음과 같습니다.

  jsonPayload.":name":apple

  jsonPayload."foo.bar":apple

  jsonPayload."\"foo\"":apple

특수문자 목록은 값 및 변환string 섹션을 참조하세요.

객체나 배열을 참조하는 필드 경로 식별자의 사용에 관한 자세한 내용은 이 페이지의 객체 및 배열 유형을 참조하세요.

모니터링 리소스 유형

더 빠른 쿼리를 위해 모니터링 리소스 유형을 지정합니다. 리소스 유형 목록은 모니터링 리소스 유형을 참조하세요.

예를 들어 Compute Engine VM은 gce_instance 리소스 유형을, Amazon EC2 인스턴스는 aws_ec2_instance를 사용합니다. 다음 예시는 쿼리를 두 가지 유형의 VM으로 제한하는 방법을 보여줍니다.

    resource.type = ("gce_instance" OR "aws_ec2_instance")

로그의 모니터링 리소스 유형 값에는 색인이 생성됩니다. 여기에 하위 문자열 일치를 사용하면 쿼리의 실행 속도가 더 늦어집니다.

누락 필드

쿼리에서 사용된 필드가 로그 항목에 표시되지 않으면 필드가 누락되었거나, 정의되지 않았거나, 기본값이 적용된 경우입니다.

  • 필드가 로그 항목의 페이로드(jsonPayload 또는 protoPayload)의 일부이거나 로그 항목 labels 섹션의 라벨에 있으면 필드가 누락됩니다. 누락된 필드를 사용하면 오류가 표시되지 않지만, 누락된 필드를 사용한 모든 비교는 자동으로 실패합니다.

    예: jsonPayload.nearest_store, protoPayload.name.nickname

  • 필드가 LogEntry 유형으로 정의되면 이 필드에 기본값이 적용됩니다. 필드가 존재하고 기본값이 있는 경우처럼 비교가 수행됩니다.

    예: httpRequest.remoteIp, trace, operation.producer

  • 그렇지 않으면 필드가 정의되지 않은 경우로, 쿼리를 사용하기 전에 오류로 감지됩니다.

    예: thud, operation.thud, textPayload.thud

필드의 특정 값을 테스트하지 않고 누락된 필드나 기본값이 적용된 필드가 있는지 테스트하려면 :* 비교를 사용하세요. 예를 들어 로그 항목에 operation.id 필드가 명시적으로 있으면 다음 비교는 성공합니다.

operation.id:*

다음 쿼리의 동작을 확인합니다.

  • 누락된 필드에서 부울 NOT 연산자를 사용하면 결과는 TRUE입니다.

    # Returns TRUE
    NOT missingField=foo
    
  • 누락된 필드에 같지 않음 비교 연산자 !=를 사용하면 결과는 FALSE입니다.

    # Returns FALSE
    missingField!=foo
    

객체 및 배열 유형

각 로그 항목 필드는 스칼라, 객체 또는 배열을 저장할 수 있습니다.

  • 스칼라 필드는 174.4 또는 -1과 같은 단일 값을 저장합니다. string도 스칼라로 간주됩니다. DurationTimestamp와 같이 문자열로(또는 문자열에서) 변환될 수 있는 필드도 스칼라 유형입니다.

  • 객체 유형은 다음 JSON 값과 같이 이름이 지정된 값의 모음을 저장합니다.

    {"age": 24, "height": 67}
    

    객체 내부의 값을 참조할 수 있습니다. 예를 들어 jsonPayload.x에 앞의 값이 포함되어 있으면 jsonPayload.x.age의 값이 24가 됩니다.

  • 배열 필드는 동일한 유형의 값 목록을 저장합니다. 예를 들어 측정 값을 포함하는 필드에 숫자 배열이 있을 수 있습니다.

    {8.5, 9, 6}
    

    비교가 수행될 때 [FIELD_NAME]이 배열 필드인 경우 배열의 각 구성원이 [VALUE]와 비교되고 그 결과가 OR 연산자를 사용하여 하나로 결합됩니다. 예를 들어 jsonPayload.shoeSize{8.5, 9, 6}을 저장하는 배열 필드이면 비교는 다음과 같습니다.

    jsonPayload.shoeSize < 7
    

    이 값은 다음과 동일합니다.

    8.5 < 7 OR 9 < 7 OR 6 < 7
    

    이 예에서 전체 비교는 성공한 것으로 평가됩니다.

값과 변환

비교를 평가하는 첫 번째 단계는 오른쪽 값을 로그 항목 필드의 유형으로 변환하는 것입니다. 비교 시 스칼라 필드 유형과 값이 DurationTimestamp로 표현되는 다른 두 가지 유형을 함께 사용할 수 있습니다. 스칼라 유형 목록은 스칼라 프로토콜 버퍼 유형 목록을 참조하세요. 다음 표에는 로그 필드 유형으로 변환할 수 있는 값이 나와 있습니다.

필드 유형 허용되는 쿼리 값
bool

대소문자에 관계없이 모든 'true' 또는 'false'. 예: 'True', 'true'

bytes

모든 시퀀스의 바이트를 포함하는 문자열. 예: '\377\377'.

Duration

부호가 있고 단위 'ns', 'us', 'ms', 's', 'm', 'h' 중 하나가 뒤에 오는 10진수가 포함된 문자열. Durations(기간)는 나노초 단위까지 표시됩니다. 예: '3.2초'

enum

열거형 유형 리터럴의 이름으로 대소문자를 구분하지 않음. 예: '경고'(LogSeverity 유형의 값)

double

부호와 지수 부분이 있거나 없는 숫자 또는 특수값 문자열 'NaN', '-Infinity', 'Infinity'(대문자 또는 아님). 예: '-3.2e-8', 'nan'.

intNN

유형의 크기를 초과하지 않고 부호가 있는 정수. 예: '-3'.

string

UTF-8 인코딩 텍스트 또는 7비트 ASCII 텍스트를 포함하는 문자열. 삽입된 따옴표는 백슬래시로 이스케이프 처리합니다.

문자열 값을 큰따옴표로 묶어 다음 특수문자를 이스케이프 처리해야 합니다.

  • +(더하기), -(빼기) 또는 .(마침표)로 시작하는 문자열

  • ~(물결 표시), =(등호), ()(괄호), :(콜론), >(초과), <(미만), ,(쉼표) 또는 .(마침표)가 있는 문자열

  • 이스케이프 시퀀스(예: \t)

Timestamp

RFC 3339 또는 ISO 8601 형식 문자열. 예: '2014-10-02T15:01:23.045Z'(RFC 3339), '2014-10-02'(ISO 8601) 쿼리 표현식에서 RFC 3339 형식의 타임스탬프는 'Z' 또는 ±hh:mm으로 시간대를 지정할 수 있습니다. 타임스탬프는 나노초 단위까지 표시됩니다.

uintNN

유형의 크기를 초과하지 않고 부호가 없는 정수. 예: '1234'.

변환을 시도했는데 실패할 경우 비교가 실패합니다.

변환에 문자열이 필요한 경우, 공백이나 연산자 같은 특수 문자가 포함되어 있지 않으면 숫자나 따옴표 없는 텍스트를 사용할 수도 있습니다. 마찬가지로, 변환 시 숫자가 필요한 경우 숫자가 포함된 문자열을 사용할 수 있습니다.

intNN 유형과 uintNN 유형은 int32uint64와 같이 다양한 크기의 정수 유형을 표현합니다. 64비트 정수 유형으로 변환될 값을 작성할 경우 이 값을 '9223372036854775807'과 같은 문자열로 작성합니다.

로그 필드 유형

로그 항목 필드의 유형이 결정되는 방식은 다음과 같습니다.

  • LogEntry 유형과 구성요소 유형에서 정의된 로그 필드는 프로토콜 버퍼 필드입니다. 프로토콜 버퍼 필드는 명시적 유형입니다.

  • protoPayload 객체의 일부인 로그 필드도 프로토콜 버퍼 필드이고 명시적 유형입니다. 프로토콜 버퍼 유형의 이름은 protoPayload"@type"에 저장됩니다. 자세한 내용은 JSON 매핑을 참조하세요.

  • jsonPayload 내부의 로그 필드 유형은 로그 항목이 수신될 때 필드의 값에서 유추됩니다.

    • 따옴표로 묶이지 않은 숫자를 값으로 가지는 필드는 double 유형입니다.
    • true 또는 false 값을 가지는 필드는 bool 유형입니다.
    • 문자열을 값으로 가지는 필드는 string 유형입니다.

    긴 정수(64비트)는 double 값으로 정확하게 표현될 수 없기 때문에 문자열 필드에 저장됩니다.

  • Duration 유형과 Timestamp 유형은 프로토콜 버퍼 필드에서만 인식됩니다. 그 외의 경우에는 문자열 필드에 값이 저장됩니다.

비교 연산자

등호 연산자(=, !=)와 부등 연산자(<, <=, >, >=)의 의미는 왼쪽 필드 이름의 기본 유형에 따라 결정됩니다.

  • 모든 숫자 유형: 숫자에 대한 일반적인 등호와 부등을 의미합니다.
  • bool: 등호는 부울 값이 동일함을 의미합니다. 부등은 true>false로 정의됩니다.
  • enum: 등호는 열거형 값이 동일함을 의미합니다. 부등은 열거형 리터럴의 기본 숫자 값을 사용합니다.
  • Duration: 등호는 기간이 동일함을 의미합니다. 부등은 기간의 길이에 따라 결정됩니다. 예: 기간 "1s">"999ms"
  • Timestamp: 등호는 동일한 순간을 의미합니다. abTimestamp 값이면 a < ba가 시간순으로 b보다 먼저임을 의미합니다.
  • bytes: 피연산자는 바이트별로 왼쪽에서 오른쪽으로 비교됩니다.
  • string: 비교 시 대소문자를 구분하지 않습니다. 특히 먼저 피연산자 두 개 모두가 NFKC_CF 유니코드 정규화를 사용하여 정규화된 후 사전식 비교를 사용합니다. 그러나 정규 표현식 검색은 정규화되지 않습니다. 정규 표현식을 사용하여 로그 항목을 검색하는 방법에 대한 자세한 내용은 정규 표현식을 사용하여 로그 항목 쿼리 및 필터링을 참조하세요.

하위 문자열 연산자(:)는 stringbytes에 적용될 수 있으며 오른쪽 피연산자가 왼쪽 필드의 일부분과 같으면 된다는 점을 제외하고 등호처럼 처리됩니다. 색인이 지정된 필드의 하위 문자열 일치는 로그 색인을 사용하지 않습니다.

전역 제한

하나의 값으로 구성된 비교를 전역 제한이라고 합니다. Logging은 has(:) 연산자를 사용하여 로그 항목의 필드 또는 페이로드에 전역 제한이 포함되어 있는지 확인합니다. 일치하면 비교가 성공합니다.

전역 제한으로 작성된 가장 간단한 쿼리는 단일 값입니다.

"The Cat in The Hat"

ANDOR 연산자로 전역 제한을 결합하여 보다 정교한 쿼리를 만들 수 있습니다. 예를 들어 cat이 포함된 필드와 hat 또는 bat이 포함된 필드가 있는 모든 로그 항목을 표시하려면 쿼리를 다음과 같이 작성합니다.

(cat AND (hat OR bat))

이 경우 cat, hat, bat라는 세 가지 전역 제한이 있습니다. 이러한 전역 제한은 개별적으로 적용되며 그 결과는 표현식이 괄호 없이 작성된 것처럼 하나로 결합됩니다.

전역 제한은 로그에서 특정 값을 쉽게 쿼리할 수 있는 방법입니다. 예를 들어 활동 로그에서 GCE_OPERATION_DONE이 포함된 항목을 찾으려면 다음 쿼리를 사용하면 됩니다.

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log" AND
    "GCE_OPERATION_DONE"

전역 제한은 쉽지만 속도가 느릴 수 있습니다. 자세한 내용은 이 페이지의 로그 항목 빨리 찾기를 참조하세요.

함수

function = identifier ( [ argument { , argument } ] )

여기서 argument는 값, 필드 이름 또는 괄호로 묶은 표현식입니다. 다음 섹션에서는 함수를 설명합니다.

log_id

log_id 함수는 logName 필드에서 지정된 [LOG_ID] 인수와 일치하는 로그 항목을 반환합니다.

  log_id([LOG_ID])

예를 들어 다음 쿼리는 cloudaudit.googleapis.com%2Factivity [LOG_ID]가 있는 모든 로그 항목을 반환합니다.

  log_id("cloudaudit.googleapis.com/activity")

sample

sample 함수는 총 로그 항목 개수의 일정 비율을 선택합니다.

sample([FIELD], [FRACTION])

[FIELD]는 로그 항목에 있는 필드의 이름입니다(예: logName 또는 jsonPayload.a_field). 필드 값에 따라 샘플에 로그 항목이 있는지 여부가 결정됩니다. 필드 유형은 문자열 또는 숫자 값이어야 합니다. 각 로그 항목마다 필드의 값이 다르므로 [FIELD]insertId로 설정하는 것이 좋습니다.

[FRACTION][FIELD]에 포함할 값이 있는 로그 항목의 비율로, 0.0보다 크고 1.0보다 크지 않은 숫자입니다. 예를 들어 0.01을 지정하면 샘플에 [FIELD]에 대한 값을 가진 모든 로그 항목의 약 1%가 포함됩니다. [FRACTION]이 1이면 [FIELD]에 값이 있는 모든 로그 항목이 선택됩니다.

: 다음 쿼리는 syslog 로그에서 로그 항목의 25%를 반환합니다.

    logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)

세부정보: 해싱을 기반으로 하는 결정적 알고리즘은 로그 항목이 샘플에 포함되는지 또는 샘플에서 제외되는지 여부를 확인하는 데 사용됩니다. 생성된 샘플의 정확도는 해시된 값의 분포에 따라 달라집니다. 해시된 값이 일정하게 분포되지 않으면 생성된 샘플이 왜곡될 수 있습니다. 최악의 경우 [FIELD]에 항상 동일한 값이 포함되면 샘플에 모든 로그 항목의 [FRACTION]이 포함되거나 로그 항목이 아예 포함되지 않습니다.

[FIELD]가 로그 항목에 나타나면 다음과 같이 처리됩니다.

  • 값의 해시가 계산됩니다.
  • 해시된 값(숫자)가 가능한 최대 해시 값으로 나뉩니다.
  • 그 비율이 [FRACTION]보다 작거나 같으면 로그 항목이 샘플에 포함됩니다. 그렇지 않으면 샘플에서 제외됩니다.

[FIELD]가 로그 항목에 나타나지 않으면 다음과 같이 처리됩니다.

  • [FIELD]가 로그 항목의 페이로드 또는 labels 섹션의 일부이면 [FRACTION]이 1이어도 로그 항목이 샘플에 선택되지 않습니다.
  • 그렇지 않으면 로그 항목은 [FIELD]가 로그 항목에 있고 [FIELD] 값이 기본값인 것처럼 처리됩니다. 기본값은 LogEntry 유형에 따라 결정됩니다. 누락된 필드와 기본값이 적용된 필드에 관한 자세한 내용은 누락 필드를 참조하세요.

기본값이 적용된 필드가 있는 로그 항목을 샘플에서 제외하려면 필드-존재 연산자 :*을 사용하세요. 다음 쿼리는 field에 값을 명시적으로 제공한 로그 항목의 1% 샘플을 생성합니다.

field:* AND sample(field, 0.01)

ip_in_net

ip_in_net 함수는 로그 항목의 IP 주소가 서브넷에 포함되는지 여부를 판단합니다. 이 함수를 사용하면 요청이 내부 소스에서 전송되었는지 또는 외부 소스에서 전송되었는지 알 수 있습니다. 예를 들면 다음과 같습니다.

ip_in_net([FIELD], [SUBNET])

[FIELD]는 IP 주소나 범위를 포함하는 로그 항목의 문자열 값 필드입니다. 이 필드는 반복될 수 있으며, 이 경우 반복된 필드 중 하나에만 서브넷에 포함된 주소나 범위가 지정됩니다.

[SUBNET]은 IP 주소 또는 범위의 문자열 상수입니다. 이 섹션의 뒷부분에 설명된 대로 [SUBNET]이 유효한 IP 주소 또는 범위가 아니면 오류가 발생합니다.

: 다음 쿼리는 my_log 로그에서 로그 항목의 페이로드에 있는 IP 주소를 테스트합니다.

    logName = "projects/my_project/logs/my_log" AND
    ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")

세부정보: 로그 항목에서 [FIELD]가 누락되거나, 기본값이 적용되거나, 유효한 IP 주소 또는 범위가 포함되지 않으면 함수는 false를 반환합니다. 누락된 필드와 기본값이 적용된 필드에 관한 자세한 내용은 누락 필드를 참조하세요.

지원되는 IP 주소 및 범위의 예시는 다음과 같습니다.

  • IPv4: 10.1.2.3
  • IPv4 서브넷: 10.1.2.0/24
  • CIDR IPv6: 1234:5678:90ab:cdef:1234:5678:90ab:cdef
  • CIDR IPv6 서브넷: 1:2::/48

시간으로 검색

인터페이스에서 로그 항목을 표시할 날짜와 시간에 특정 제한을 설정할 수 있습니다. 예를 들어 다음 조건을 쿼리에 추가하면 로그 탐색기는 표시된 30분 동안만 로그 항목을 표시하며 이 기간 이외에는 스크롤할 수 없습니다.

timestamp >= "2016-11-29T23:00:00Z"
timestamp <= "2016-11-29T23:30:00Z"

타임스탬프 쿼리를 작성할 경우 날짜와 시간을 위와 같은 형식으로 사용해야 합니다.

timestamp 단축키를 사용하여 로그 항목을 검색할 수도 있습니다. 예를 들어 비교 연산자를 사용하여 날짜를 입력하면 특정 날짜 이후의 모든 로그 항목을 가져올 수 있습니다.

  timestamp > "2016-11-29"

정규 표현식 사용

정규 표현식을 사용하여 쿼리를 빌드하고 싱크, 측정항목, 로그 필터가 사용되는 위치에 대한 필터를 만들 수 있습니다. 쿼리 빌더gcloud command-line tool에서 정규 표현식을 사용할 수 있습니다.

정규 표현식은 검색을 정의하는 일련의 문자입니다. 쿼리 언어는 RE2 구문을 사용합니다. RE2 구문에 대한 자세한 설명은 GitHub의 RE2 위키를 참조하세요.

정규 표현식 쿼리의 특징은 다음과 같습니다.

  • 문자열 유형의 필드만 정규 표현식과 일치할 수 있습니다.

  • 문자열 정규화는 수행되지 않습니다. 예를 들어 kubernetesKUBERNETES와 동일하지 않습니다. 자세한 내용은 비교 연산자 섹션을 참조하세요.

  • 쿼리는 대소문자를 구분하며 기본적으로 고정되어 있지 않습니다.

  • 부울 연산자를 정규 표현식 비교 연산자(=~!~) 오른쪽에 있는 여러 정규 표현식에서 사용할 수 있습니다.

정규 표현식 쿼리 구조는 다음과 같습니다.

패턴 일치:

jsonPayload.message =~ "regular expression pattern"

패턴과 일치하지 않음:

jsonPayload.message !~ "regular expression pattern"

=~!~는 쿼리를 정규 표현식 쿼리로 변경하며 일치시키려는 패턴은 큰따옴표 안에 있어야 합니다. 큰따옴표를 포함하는 패턴을 쿼리하려면 백슬래시를 사용하여 이스케이프 처리합니다.

정규 표현식을 사용하여 로그를 쿼리하는 예시

쿼리 유형 예시
표준 쿼리 sourceLocation.file =~ "foo"
대소문자를 구분하지 않는 검색 쿼리 labels.subnetwork_name =~ "(?i)foo"
따옴표가 포함된 쿼리 jsonPayload.message =~ "field1=\"bar.*\""
부울 or를 사용하는 쿼리 labels.pod_name =~ "(foo|bar)"
앵커를 사용하는 쿼리 logName =~ "/my%2Flog$"
패턴과 일치하지 않는 쿼리 labels.pod_name !~ "foo"
부울 연산자를 사용하는 쿼리 labels.env =~ ("^prod.*server" OR "^staging.*server")

로그 항목 빨리 찾기

보다 효율적으로 로그 항목을 찾으려면 다음을 수행합니다.

  • 색인이 생성된 필드를 사용하여 쿼리합니다.
  • 검색되어야 하는 로그 항목의 개수를 최소화합니다.

색인이 생성된 필드 사용

다음 LogEntry 필드에는 색인이 생성되어 있습니다.

다음 섹션에서는 이러한 색인이 생성된 필드를 사용하여 쿼리할 로그 항목의 개수를 최소화하는 방법을 설명합니다.

쿼리 최적화

로그 수, 로그 항목 수, 검색 시간 범위를 제한하면 더 빠르게 검색할 수 있습니다. 이 세 가지 조건을 모두 줄이면 더 좋습니다.

예: 올바른 로그 이름 사용

관심 있는 로그 항목이 포함된 로그를 지정하세요. 로그 항목 중 하나를 검사하여 실제 로그 이름을 파악하세요. 예를 들어 기존 로그 뷰어에는 Compute Engine 섹션에 'activity'라는 로그가 있다고 표시됩니다. 관리자 활동 로그 항목을 자세히 살펴보면 실제 로그 이름은 'cloudaudit.googleapis.com/activity'입니다.

다음 비교는 잘못되었습니다. 잘못된 로그 이름을 사용하고 있기 때문에 어떤 것과도 일치하지 않습니다.

    logName = "projects/my-project-id/logs/activity"   # WRONG!

다음 비교는 올바릅니다. 관리자 활동 감사 로그에서 로그 항목을 선택합니다. 다음과 같이 로그 이름을 URL로 인코딩해야 합니다.

    logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

예: 올바른 로그 항목의 선택

원하는 로그 항목이 특정 VM 인스턴스에서 온다는 것을 알고 있으면 해당 인스턴스를 지정하세요. 검색하려는 로그 항목 중 하나를 검사하여 라벨 이름이 올바른지 확인하세요. 다음 예시에서 instance_id는 색인이 생성된 라벨 중 하나입니다.

    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"
    logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

예시: 올바른 기간 선택

검색할 기간을 지정해야 합니다. RFC 3339 형식의 유용한 타임스탬프를 결정하는 빠른 방법은 Gnu/Linux date 명령어를 사용하는 것입니다.

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

다음 쿼리에 이 타임스탬프 값을 사용하세요. Logging에서 사용할 수 있는 타임스탬프를 만들려면 날짜와 시간 사이의 공백을 문자 T로 바꿉니다.

예를 들어 최근 3시간 범위 내에서 검색하려면 다음을 사용하세요.

    timestamp >= "2016-06-27T14:40:00-04:00"

또 다른 예로 3시간에서 5시간 전 사이의 범위에서 검색하려면 다음을 사용하세요.

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

타임스탬프를 사용하는 그 밖의 예시는 이 페이지의 임시 필드 색인을 참조하세요.

전체 검색과 하위 문자열 검색의 최소화

로깅 쿼리를 입력할 때 간편한 방법을 찾으려고 시도하지 마세요.

예시: 전체 검색을 사용하지 마세요.

페이로드에 'Hello, Kitty'가 포함된 로그 항목을 검색하려고 합니다.

  • 전체 검색을 사용하지 마세요. 한 가지 이유는 전체 검색이 모두 하위 문자열 검색이기 때문입니다.

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • 하위 문자열 검색을 유지해야 하더라도 검색 대상을 단일 필드로 제한하세요.

        textPayload:"Hello, Kitty"
    
  • 가능하다면 동일성 테스트를 사용하세요.

        textPayload = "Hello, Kitty"
    
  • 로그 항목에 구조화된 페이로드가 있는 경우 페이로드의 각 필드를 참조하세요.

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • 색인이 지정된 필드를 사용하여 검색 범위를 제한하세요.

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

검색의 예

아래의 로그 항목은 검색어 상자의 고급 로그 쿼리와 일치하는 로그 항목입니다. 이동할 날짜 메뉴에 값이 포함되어 있으면 화면이 그 시점까지 스크롤됩니다. 다음은 몇 가지 쿼리 예시입니다.

resource.type=gae_app

리소스 로그 메뉴에서 GAE 애플리케이션(모든 모듈 IDs)을, 로그 이름 메뉴에서 모든 로그를 선택한 경우 기본 쿼리 인터페이스에 표시되는 로그 항목과 동일한 로그 항목을 찾습니다. 리소스 유형 목록은 모니터링 리소스 목록을 참조하세요.

입력과 동시에 기존 로그 뷰어는 resource.type과 같은 전체 필드 이름을 제안합니다.

resource.type=gae_app AND logName:request_log

request_log를 포함하는 로그 이름에서 App Engine 앱의 로그 항목을 찾습니다. 다음과 같은 사항에 유의하세요.

  • = 연산자는 100% 동일입니다. 리소스 유형은 대소문자에 관계없이 정확히 "gae_app"이어야 합니다.
  • : 연산자는 'has'를 의미합니다. logName 필드에는 대소문자에 관계없이 request_log가 포함되어야 합니다. 실제 로그 이름은 훨씬 더 깁니다. :을 사용하면 검색 속도가 더 느려질 것입니다.
  • 비교가 2개인 경우 AND로 결합합니다. OR을 사용해도 되지만 연산자를 빼버리면 AND로 간주됩니다.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Compute Engine VM 인스턴스와 AWS EC2 VM 인스턴스의 두 가지 리소스 유형 중 하나가 있는 로그 항목을 찾습니다. 로그 항목의 severity는 최소한 ERROR여야 합니다. 이는 기본 쿼리 인터페이스의 심각도 메뉴에서 오류를 선택하는 것과 같습니다. 기본 쿼리 인터페이스에는 여러 리소스 유형의 로그가 표시되지 않습니다.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

[PROJECT_ID] 프로젝트에서 모든 관리자 활동 감사 로그 항목을 찾습니다. 한 프로젝트 내의 감사 로그는 모두 동일한 로그 이름을 사용하지만 리소스 유형은 서로 다릅니다. 로그 ID cloudaudit.googleapis.com/activity는 로그 이름에서 URL로 인코딩되어야 합니다. 비교 시 등호를 사용하면 검색 속도가 빨라집니다. 자세한 내용은 감사 로그 이해를 참조하세요.

unicorn

특정 필드에서 대소문자에 관계없이 unicorn이 포함된 로그 항목을 찾습니다. 필드 비교의 일부가 아닌 검색어는 '모든 필드' 쿼리입니다.

unicorn phoenix

일부 필드에는 unicorn, 일부 필드에는 phoenix가 포함된 로그 항목을 찾습니다.

textPayload:(unicorn phoenix)

textPayload 필드에 순서에 관계없이 unicornphoenix이 포함된 로그 항목을 찾습니다. 이때 AND는 두 단어 사이에 내포되어 있습니다.

textPayload:"unicorn phoenix"

textPayload 필드에 "unicorn phoenix"라는 문자열이 포함된 로그 항목을 찾습니다. 이는 기본 쿼리 인터페이스와 동일합니다.

NOT textPayload: "unicorn phoenix"

textPayload 필드에 "unicorn phoenix" 문자열이 포함되지 않은 로그 항목을 찾습니다. 이 유형의 쿼리는 원치 않는 로그 항목을 줄입니다.

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

30분 기간 내의 로그 항목을 찾습니다.

문제해결

키보드 탐색

키보드를 사용하여 검색어 상자에 고급 쿼리를 입력하고 페이지의 다른 메뉴로 이동해야 하면 ESC 키를 눌러 수정 모드를 종료한 다음 TAB 키를 눌러 다른 옵션으로 이동합니다.

구문 문제

고급 쿼리의 표현식에 문제가 있는 경우 다음 사항을 확인해 보세요.

  • 쿼리가 구문 규칙을 준수하며 괄호와 따옴표가 제대로 되어 있습니다. 쿼리에 주석을 추가할 수 없습니다.

  • 로그 항목 필드 이름의 철자가 올바릅니다.

  • 부울 연산이 대문자로 되어 있습니다(AND, OR, NOT).

  • 전역 제한 형태의 부울 표현식 또는 비교의 오른쪽에 있는 부울 표현식은 괄호로 묶어서 명확하게 구분하는 것이 좋습니다. 예를 들어 아래의 쿼리 2개는 같아 보이지만 다릅니다.

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • 따옴표로 묶여 있지 않은 텍스트에 특수문자가 있어서는 안 됩니다. 확실하지 않다면 큰따옴표를 추가하세요. 예를 들어 아래의 첫 번째 비교는 하위 문자열 연산자(:)가 삽입되어 있으므로 잘못되었습니다. 비교는 따옴표로 묶어서 작성해야 합니다.

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • gcloud 명령줄 도구에서는 쿼리를 큰따옴표로 묶어야 합니다. gcloud logging 명령어를 사용하여 특수문자를 이스케이프하기 위해 큰 따옴표를 사용하려면 전체 쿼리를 작은따옴표로 묶으세요.

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
    
  • 기존 로그 뷰어 기본 쿼리의 검색 표현식은 고급 로그 쿼리의 검색 표현식과 다릅니다. 자세한 내용은 기본 쿼리와 고급 쿼리의 차이를 참조하세요.

  • 타임스탬프가 포함된 쿼리를 작성하는 경우에는 검색어 상자 아래에 있는 시간 범위 선택기에서 제한 없음을 선택해야 합니다.