고급 로그 필터

이 가이드에서는 로그 개수에 관계없이 로그에서 로그 항목 집합을 지정할 수 있는 표현식인 고급 로그 필터를 작성하는 방법을 설명합니다. 로그 뷰어, Stackdriver Logging API, 명령줄 인터페이스에서 고급 로그 필터를 사용할 수 있습니다.

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

로그의 추천 필터 목록은 고급 필터 라이브러리를 참조하세요.

소개

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

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

고급 로그 필터 시작하기

로그 뷰어에서 고급 필터를 사용하려면 다음 단계를 따르세요.

  1. GCP Console에서 Stackdriver Logging > 로그(로그 뷰어) 페이지로 이동합니다.

    로그 뷰어 페이지로 이동

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

  3. 드롭다운 메뉴를 사용하여 표시할 로그의 리소스를 선택합니다.

  4. 검색 필터 상자 오른쪽 끝에 있는 드롭다운 화살표(▾)를 클릭하고 고급 필터로 전환을 선택합니다.

    고급 로그 필터로 변환

아래와 같은 고급 필터 인터페이스가 표시됩니다.

고급 로그 필터 UI

로그 선택 메뉴가 없고 필터 제출 버튼이 있으면 이를 통해 고급 필터 인터페이스임을 알 수 있습니다. 로그 뷰어에는 필터에 지정된 모든 조건을 충족하는 로그 항목이 표시됩니다.

다음은 고급 필터의 간단한 예시입니다.

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

이 필터는 심각도 값이 최소한 ERROR이고 textPayload 필드에 robot 문자열이 포함되지 않은 Compute Engine의 로그 항목과 일치합니다. 문자열 비교는 대소문자를 구분하지 않습니다. 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:*

객체 및 배열 유형

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

  • scalar 필드는 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 형식의 문자열. 예: '2014-10-02T15:01:23.045Z'. 필터 표현식에서 타임스탬프는 'Z' 또는 ±hh:mm으로 시간대를 지정할 수 있습니다. 타임스탬프는 나노초 단위까지 표시됩니다.
uintNN 유형의 크기를 초과하지 않고 부호가 없는 정수. 예: '1234'.

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

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

유형 intNNuintNNint32uint64와 같이 다양한 크기의 정수 유형을 표현합니다. 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는 값, 필드 이름 또는 괄호로 묶은 표현식입니다. 함수에 관해서는 다음 섹션에서 설명합니다.

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"

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

로그 항목 빨리 찾기

로그 항목을 필터링하거나 쿼리할 때 다음을 수행하세요.

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

색인이 지정된 필드 사용

색인이 지정된 필드에 정확한 값을 지정합니다. 하위 문자열 일치를 사용하지 마세요. 다음과 같은 로그 항목 필드에 색인이 지정되어 있습니다.

임시 필드 색인

Stackdriver Logging이 로그 항목을 수신한 후 한정된 시간 동안 3개의 추가 로그 항목 필드에 색인이 부분적으로 지정됩니다. 시스템의 문제에 신속하게 대응하려면 이러한 필드에서 검색하는 것이 도움이 될 것입니다. 향후 Stackdriver Logging은 별도의 고지 없이 이러한 3개 필드에 색인을 지정하는 방식을 변경할 수 있습니다.

  • severity: NOTICE(100)에서 EMERGENCY(900)까지의 심각도 값이 색인으로 지정됩니다. 이 색인을 이용하려면 색인이 지정되는 범위 내의 값만 검색하세요.

  • httpRequest.status: 201에서 511까지의 상태 값이 색인으로 지정됩니다. 이 색인을 이용하려면 색인이 지정되는 범위 내의 값만 검색하세요.

  • operation.id: 이 필드의 모든 값에 색인이 지정됩니다. 색인을 이용하려면 등호 연산자를 사용하여 이 필드를 검색하세요. 하위 문자열 검색은 사용하지 마세요.

최근 로그 항목에서 이러한 필드를 일상적으로 검색한다면 timestamp 필드를 사용하여 검색 기간을 제한하는 것도 고려해봐야 합니다.

로그, 로그 항목, 시간의 최소화

로그의 개수, 로그 항목의 개수, 검색 시간 범위를 줄여서 검색을 더 빨리 수행하세요. 이 세 가지를 모두 줄이면 더 좋습니다.

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

관심 있는 로그 항목이 포함된 로그를 지정하세요. 로그 항목 중 하나를 검사하여 실제 로그 이름을 파악하세요. 예를 들어 로그 뷰어에는 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

이러한 타임스탬프의 값을 다음 필터에 사용하세요. Stackdriver 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] 프로젝트에서 모든 관리 활동 감사 로그 항목을 찾습니다. 감사 로그는 한 프로젝트 내에서 항상 동일한 로그 이름을 사용하지만 리소스 유형이 서로 다릅니다. cloudaudit.googleapis.com/activity라는 로그 ID의 로그 이름은 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 logging에서는 필터를 큰따옴표로 묶어야 합니다. gcloud logging 명령어를 사용하여 특수문자를 이스케이프하기 위해 큰따옴표를 사용하려면 전체 필터를 작은따옴표로 묶습니다.

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    
  • 로그 뷰어 기본 필터의 검색 표현식은 고급 로그 필터의 검색 표현식과 다릅니다. 자세한 내용은 기본 필터와 고급 필터의 차이를 참조하세요.

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

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

Stackdriver Logging
도움이 필요하시나요? 지원 페이지를 방문하세요.