고급 로그 쿼리

이 가이드에서는 로그 뷰어(기본)를 사용하여 로그 개수에 관계없이 로그에서 로그 항목 집합을 지정할 수 있는 표현식인 고급 로그 쿼리를 작성하는 방법을 설명합니다. 고급 로그 쿼리는 로그 뷰어(기본), 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"
        

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

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

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

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

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

첫 번째 비교에서는 cat 필드의 값이 'siamese' 또는 '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 필드는 문자열이므로 다음에 어떤 하위 필드 이름도 올 수 없습니다.

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

모니터링 리소스 유형

더 빨리 검색하려면 모니터링 리소스 유형을 지정하세요. 리소스 유형 목록은 모니터링 리소스 유형을 참조하세요.

예를 들어 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:*
    

객체 및 배열 유형

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

  • 스칼라 필드는 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 텍스트를 포함하는 문자열. 삽입된 따옴표는 백슬래시로 이스케이프 처리합니다.
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'.

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

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

intNNuintNN 유형은 int32uint64와 같이 다양한 크기의 정수 유형을 표현합니다. 64비트 정수 유형으로 변환될 값을 작성할 때는 이 값을 '9223372036854775807' 같은 문자열로 작성하는 것이 좋습니다.

로그 필드의 유형

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

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

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

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

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

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

  • DurationTimestamp 유형은 프로토콜 버퍼 필드{:class="external"}에서만 인식됩니다. 그 외의 경우에는 문자열 필드에 값이 저장됩니다.

비교 연산자

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

  • 모든 숫자 유형: 숫자 유형일 경우 일반적인 등호와 부등을 의미합니다.
  • 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는 값, 필드 이름 또는 괄호로 묶은 표현식입니다. 함수에 관해서는 다음 섹션에서 설명합니다.

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"
    

타임스탬프 쿼리를 작성할 때 날짜와 시간을 위에 표시된 형식으로 사용해야 합니다. 검색어 상자 아래에 있는 시간 범위 선택기에서 제한 없음을 선택해야 합니다.

로그 항목 빨리 찾기

보다 효율적으로 로그 항목을 찾으려면 다음 안내를 따르세요.

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

색인이 지정된 필드 사용

색인을 활용하려면 등호 연산자를 사용하여 색인이 지정된 필드에 정확한 값을 지정합니다. 하위 문자열 일치를 사용하지 마세요.

다음과 같은 LogEntry 필드에 색인이 지정되어 있습니다.

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

쿼리 최적화

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

예: 올바른 로그 이름의 사용

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

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

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

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

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

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

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

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

리소스 유형에 값을 지정해야 합니다. 그렇지 않으면 instance_id 비교 시 색인이 사용되지 않습니다.

예: 올바른 기간의 선택

검색 범위가 되는 기간을 지정하는 것이 좋습니다. 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"
    

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

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

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

예: 색인이 지정된 필드에 하위 문자열을 사용하지 마세요.

Apache2 웹 서버에서 로그 항목을 검색하려고 한다고 가정해보세요. 그리고 Apache 로그의 이름이 apache-accessapache-error라는 것을 알고 있다고 가정하겠습니다. 어떻게 하시겠습니까?

  • 입력 시간을 절약하기 위해 하위 문자열 일치를 사용하지 마세요.

        logName:apache   # THIS CAUSES A SLOW SEARCH!
        
  • 색인이 지정된 필드를 검색할 때는 100% 일치를 사용하세요.

        logName = ("projects/my-project-id/logs/apache-access" OR
                       "projects/my-project-id/logs/apache-error")
        

하위 문자열 검색을 수행하면 색인이 지정된 필드로 인해 검색 속도가 크게 저하됩니다.

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

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

입력과 동시에 로그 뷰어는 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"라는 문자열이 포함된 로그 항목을 찾습니다. 이는 기본 쿼리 인터페이스에서와 동일합니다.

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."'
        
  • 로그 뷰어 기본 쿼리의 검색 표현식은 고급 로그 쿼리의 검색 표현식과 다릅니다. 자세한 내용은 기본 쿼리와 고급 쿼리의 차이를 참조하세요.

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