학습 센터에서 Grok 구문 분석해보기

로그 파이프라인을 빌드해 수정하고, Pipeline Scanner로 관리하고 처리된 로그 전체의 속성 이름을 표준화하여 일관성을 실현하는 방법을 알아보세요.

지금 등록

개요

Datadog은 JSON 형식의 로그를 자동으로 구문 분석합니다. 다른 형식의 경우, Datadog에서 Grok 파서의 도움을 받아 로그를 강화할 수 있습니다. Grok 구문은 순수 정규식보다 로그를 더 쉽게 구문 분석할 수 있는 방법을 제공합니다 Grok 파서를 사용하면 반구조화된 텍스트 메시지에서 속성을 추출할 수 있습니다.

Grok에는 정수, IP 주소, 호스트 이름 등을 구문 분석할 수 있는 재사용 가능한 패턴이 포함되어 있습니다. 이러한 값을 Grok 파서에 문자열 형태로 보내야 합니다.

%{MATCHER:EXTRACT:FILTER} 구문을 사용하여 구문 분석 규칙을 작성할 수 있습니다.

• Matcher: 예상되는 내용(숫자, 단어, notSpace 등)을 설명하는 규칙입니다(다른 토큰 규칙에 대한 참조일 수 있음).

• Extract(선택 사항): Matcher가 매칭한 텍스트 조각의 캡처 대상을 나타내는 식별자입니다.

• Filter(선택 사항): 일치 항목을 변환할 사후 프로세서입니다.

구조화되지 않은 전형적인 로그 예시:

john connected on 11/08/2017

다음 구문 분석 규칙을 사용합니다.

MyParsingRule %{word:user} connected on %{date("MM/dd/yyyy"):date}

처리 후 다음 구조화된 로그가 생성됩니다.

{
  "user": "john",
  "date": 1575590400000
}

참고:

• Grok 파서 하나에 구문 분석 규칙이 여러 개인 경우:
  • 하나의 항목만 주어진 로그와 일치할 수 있습니다. 위에서 첫 번째로 일치하는 항목을 구문 분석합니다.
  • 각 규칙이 위의 목록에 정의된 구문 분석 규칙을 참조할 수 있습니다.
• 같은 Grok 파서 내에 고유한 규칙 이름이 있어야 합니다.
• 규칙 이름에는 영숫자, _, .만 포함해야 합니다. 규칙은 반드시 영숫자로 시작해야 합니다.
• null이나 빈 값이 포함된 속성은 표시되지 않습니다.
• 구문 분석 규칙은 로그의 시작부터 끝까지 적용되므로, 각 규칙이 로그 항목 전체와 일치하도록 정의해야 합니다.
• 특정 로그는 큰 공백을 생성할 수 있습니다. \n 및 \s+를 사용하여 줄 바꿈 및 공백을 고려하세요.

매처 및 필터

다음은 Datadog에서 기본적으로 구현되는 모든 매처 및 필터의 목록입니다.

고급 설정

Grok 프로세서 맨 밑에 있는 고급 설정 섹션을 사용하여 기본 message 속성 대신 특정 속성을 구문 분석하거나, 여러 구문 분석 규칙에서 공통 패턴을 재사용하는 도우미 규칙을 정의합니다.

특정 텍스트 속성 구문 분석

추출 대상 필드를 사용하여 주어진 텍스트 속성에 기본message 속성 대신 Grok 프로세서에 적용합니다.

예를 들어 키-값으로 구문 분석해야 하는 command.line 속성을 포함하는 로그를 생각해 보세요. command.line에서 추출하여 내용을 구문 분석하고 명령 데이터로부터 구조화된 속성을 생성합니다.

공통 패턴을 재사용하기 위해 도우미 규칙 사용

도우미 규칙 필드를 사용하여 구문 분석 규칙의 토큰을 정의하세요. 도우미 규칙을 사용하면 구문 분석 규칙 전체에서 공통 Grok 패턴을 재사용할 수 있습니다. 이것은 같은 토큰을 사용하는 같은 Grok 파서에 규칙이 여러 개 있을 때 유용합니다.

구조화되지 않은 전형적인 로그 예시:

john id:12345 connected on 11/08/2017 on server XYZ in production

다음 구문 분석 규칙 사용:

MyParsingRule %{user} %{connection} %{server}

다음 도우미 사용:

user %{word:user.name} id:%{integer:user.id}
connection connected on %{date("MM/dd/yyyy"):connect_date}
server on server %{notSpace:server.name} in %{notSpace:server.env}

예시

파서 사용법을 보여주는 몇 가지 예시:

• 키 값 또는 logfmt
• 날짜 구문 분석
• 대체 패턴
• 선택 속성
• 중첩된 JSON
• 정규식
• 목록 및 배열
• Glog 형식
• XML
• CSV

키 값 또는 logfmt

이것은 키-값 코어 필터입니다. keyvalue([separatorStr[, characterAllowList[, quotingStr[, delimiter]]]]) 자세한 내용 설명:

• separatorStr: 키와 값 사이 구분 기호를 정의합니다. 기본값은 =입니다.
• characterAllowList:기본 \\w.\\-_@ 외에 이스케이프 처리되지 않은 값 문자를 추가로 정의합니다. 따옴표가 없는 값에만 사용됩니다(예를 들어 key=@valueStr).
• quotingStr: 따옴표를 정의하여 기본 따옴표 감지 <>, "", ''를 대체합니다.
• delimiter: 서로 다른 키 값 쌍 사이의 구분 기호를 정의합니다(예를 들어 |가 key1=value1|key2=value2의 구분 기호임). 기본값은 (일반 공백), , 및 ;입니다.

keyvalue와 같은 필터를 사용하여 문자열을 keyvalue 또는 logfmt 형식의 속성으로 더 간편하게 매핑합니다.

로그:

user=john connect_date=11/08/2017 id=123 action=click

규칙:

rule %{data::keyvalue}

파라미터 이름은 이미 로그에 포함되어 있으므로 지정할 필요가 없습니다. 규칙 패턴에 추출 속성 my_attribute를 추가하면 다음과 같은 내용이 표시됩니다.

{
  "my_attribute": {
    "user": "john",
    "id": 123,
    "action": "click"
  }
}

=가 키와 값의 기본 구분 기호가 아닌 경우, 구문 분석 규칙에 구분 기호를 포함한 파라미터를 추가하세요.

로그:

user: john connect_date: 11/08/2017 id: 123 action: click

규칙:

rule %{data::keyvalue(": ")}

로그의 속성 값에 특수 문자가 포함된 경우(예를 들어 인스턴스 url에 /가 있는 경우) 이를 구문 분석 규칙의 허용 목록에 추가하세요.

로그:

url=https://app.datadoghq.com/event/stream user=john

규칙:

rule %{data::keyvalue("=","/:")}

기타 예시:

Multiple QuotingString 예시: 여러 quotingstring을 정의하면 기본 동작이 정의된 따옴표로 대체됩니다. 키-값은 quotingStr에 정의된 내용과는 관계없이 항상 따옴표 없이 입력과 일치합니다. 따옴표를 사용하는 경우, 따옴표 사이의 모든 내용을 추출하기 때문에 characterAllowList는 무시됩니다.

로그:

key1:=valueStr key2:=</valueStr2> key3:="valueStr3"

규칙:

rule %{data::keyvalue(":=","","<>")}

결과:

{"key1": "valueStr", "key2": "/valueStr2"}

참고:

• 빈 값(key=) 또는 null 값(key=null)은 출력 JSON에 표시되지 않습니다.
• data 개체에서 key-value 필터를 정의하고 이 필터가 매칭되지 않으면 빈 JSON {}가 반환됩니다(예를 들어 입력: key:=valueStr, 구문 분석 규칙: rule_test %{data::keyvalue("=")}, 출력: {}).
• ""를 quotingStr로 정의하면 인용에 대한 기본 구성이 유지됩니다.

날짜 구문 분석

날짜 매처는 타임스탬프를 EPOCH 형식으로 변환합니다(측정 단위 밀리초).

¹ 자체적으로 현지화를 수행하고 타임스탬프가 UTC 기준이 아닌 경우, timezone 파라미터를 사용하세요. 지원되는 표준 시간대 형식은 다음과 같습니다.

• GMT, UTC, UT 또는 Z
• +hh:mm, -hh:mm, +hhmm, -hhmm. 지원되는 최대 범위는 +18:00~-18:00(양쪽 끝값 포함)입니다.
• UTC+, UTC-, GMT+, GMT-, UT+ 또는 UT-로 시작하는 표준 시간대입니다. 지원되는 최대 범위는 +18:00~-18:00(양쪽 끝값 포함)입니다.
• TZ 데이터베이스에서 가져온 표준 시간대 ID입니다. 자세한 내용은 TZ 데이터베이스 이름을 참조하세요.

참고: 날짜를 구문 분석해도 그 값을 로그의 공식 날짜로 설정하지 않습니다. 이 경우 이후 프로세서에서 로그 날짜 리매퍼를 사용하세요.

대체 패턴

속성이 하나만 다른 두 가지 가능한 형식의 로그가 있는 경우 (<REGEX_1>|<REGEX_2>)를 번갈아 사용하여 단일 규칙을 설정합니다. 이 규칙은 부울 연산자 OR에 해당합니다.

로그:

john connected on 11/08/2017
12345 connected on 11/08/2017

규칙: “id"는 문자열이 아니고 정수입니다.

MyParsingRule (%{integer:user.id}|%{word:user.firstname}) connected on %{date("MM/dd/yyyy"):connect_date}

결과:
%{integer:user.id}

{
  "user": {
    "id": 12345
  },
  "connect_date": 1510099200000
}

%{word:user.firstname}

{
  "user": {
    "firstname": "john"
  },
  "connect_date": 1510099200000
}

선택 속성

일부 로그에는 시간의 일부분만 표시되는 값을 포함합니다. 이런 경우, ()?를 사용해 속성 추출을 선택 사항으로 설정하세요.

로그:

john 1234 connected on 11/08/2017
john connected on 11/08/2017

규칙:

MyParsingRule %{word:user.firstname} (%{integer:user.id} )?connected on %{date("MM/dd/yyyy"):connect_date}

참고:선택 사항 섹션의 첫 단어 뒤에 공백을 포함하면 규칙이 매칭되지 않습니다.

결과:
(%{integer:user.id} )?

{
  "user": {
    "firstname": "john",
    "id": 1234
  },
  "connect_date": 1510099200000
}

%{word:user.firstname} (%{integer:user.id} )?

{
  "user": {
    "firstname": "john",
  },
  "connect_date": 1510099200000
}

중첩된 JSON

원시 텍스트 접두사 뒤에 중첩된 JSON 개체를 구문 분석하려면 json 필터를 사용하세요.

로그:

Sep 06 09:13:38 vagrant program[123]: server.1 {"method":"GET", "status_code":200, "url":"https://app.datadoghq.com/logs/pipelines", "duration":123456}

규칙:

parsing_rule %{date("MMM dd HH:mm:ss"):timestamp} %{word:vm} %{word:app}\[%{number:logger.thread_id}\]: %{notSpace:server} %{data::json}

결과:

{
  "timestamp": 1567761218000,
  "vm": "vagrant",
  "app": "program",
  "logger": {
    "thread_id": 123
  }
}

정규식

로그:

john_1a2b3c4 connected on 11/08/2017

규칙:

MyParsingRule %{regex("[a-z]*"):user.firstname}_%{regex("[a-zA-Z0-9]*"):user.id} .*

결과:

{
  "user": {
    "firstname": "john",
    "id": "1a2b3c4"
  }
}

목록에서 배열로

목록을 속성 한 개의 배열로 추출하려면 array([[openCloseStr, ] separator][, subRuleOrFilter) 필터를 사용하세요. subRuleOrFilter는 선택 사항이며 이러한 필터를 허용합니다.

로그:

Users [John, Oliver, Marc, Tom] have been added to the database

규칙:

myParsingRule Users %{data:users:array("[]",",")} have been added to the database

결과:

{
  "users": [
    "John",
    " Oliver",
    " Marc",
    " Tom"
  ]
}

로그:

Users {John-Oliver-Marc-Tom} have been added to the database

규칙:

myParsingRule Users %{data:users:array("{}","-")} have been added to the database

**subRuleOrFilter**를 사용하는 규칙:

myParsingRule Users %{data:users:array("{}","-", uppercase)} have been added to the database

Glog 형식

Kubernetes 구성 요소는 glog 형식으로 로깅될 때가 있습니다. 이 예시는 Pipeline Library의 Kube Scheduler 항목에서 가져온 것입니다.

예시 로그 라인:

W0424 11:47:41.605188       1 authorization.go:47] Authorization is disabled

구문 분석 규칙:

kube_scheduler %{regex("\\w"):level}%{date("MMdd HH:mm:ss.SSSSSS"):timestamp}\s+%{number:logger.thread_id} %{notSpace:logger.name}:%{number:logger.lineno}\] %{data:msg}

추출된 JSON:

{
  "level": "W",
  "timestamp": 1587728861605,
  "logger": {
    "thread_id": 1,
    "name": "authorization.go"
  },
  "lineno": 47,
  "msg": "Authorization is disabled"
}

XML 구문 분석

XML 파서는 XML 형식 메시지를 JSON으로 변환합니다.

로그:

<book category="CHILDREN">
  <title lang="en">Harry Potter</title>
  <author>J K. Rowling</author>
  <year>2005</year>
</book>

규칙:

rule %{data::xml}

결과:

{
"book": {
  "year": "2005",
  "author": "J K. Rowling",
  "category": "CHILDREN",
  "title": {
    "lang": "en",
    "value": "Harry Potter"
  }
}
}

참고:

• XML에 두 개의 태그 사이에 속성과 문자열 값이 모두 있는 태그가 포함된 경우, value 속성이 생성됩니다. 예를 들어 <title lang="en">Harry Potter</title>는 {"title": {"lang": "en", "value": "Harry Potter" } }로 변환됩니다.
• 반복되는 태그는 자동으로 배열로 변환됩니다. 예를 들어 <bookstore><book>Harry Potter</book><book>Everyday Italian</book></bookstore>은 { "bookstore": { "book": [ "Harry Potter", "Everyday Italian" ] } }으로 변환됩니다.

CSV 구문 분석

CSV 필터를 사용하면 주어진 문자(기본적으로 ,)로 구분된 문자열을 속성으로 더 쉽게 매핑할 수 있습니다.

CSV 필터는 csv(headers[, separator[, quotingcharacter]])로 정의되며, 자세한 설명은 다음과 같습니다.

• headers: ,로 구분된 키 이름을 정의합니다. 키 이름은 알파벳 문자로 시작해야 하며 _와 영숫자만 포함할 수 있습니다.
• separator: 서로 다른 값을 구분하는 데 사용되는 구분 기호를 정의합니다. 문자 한 개만 허용됩니다. 기본값: ,. 참고: TSV의 표 형식 문자를 나타내려면 separator로 tab을 사용하세요.
• quotingcharacter: 따옴표를 정의합니다. 문자 한 개만 허용됩니다. 기본값: "

참고:

• 구분 기호 문자를 포함하는 값은 반드시 따옴표로 묶어야 합니다.
• 따옴표를 포함한 따옴표 값은 따옴표로 이스케이프해야 합니다. 예를 들어 따옴표로 묶인 값 안의 ""는 "를 나타냅니다.
• 로그에 헤더의 키 개수와 같은 숫자 값이 포함되지 않은 경우, CSV 파서는 첫 번째 항목을 매칭합니다.
• 가능한 경우, 정수와 double은 자동으로 캐스팅됩니다.

로그:

John,Doe,120,Jefferson St.,Riverside

규칙:

myParsingRule %{data:user:csv("first_name,name,st_nb,st_name,city")}

결과:

{
  "user": {
    "first_name": "John",
    "name": "Doe",
    "st_nb": 120,
    "st_name": "Jefferson St.",
    "city": "Riverside"
  }
}

기타 예시:

데이터 매처를 사용해 불필요한 텍스트 삭제

무엇이 필요한지 구문 분석을 마쳤고, 그 시점 이후 텍스트를 삭제해도 안전하다는 사실을 알고 있는 로그라면 데이터 매처를 사용해 삭제하면 됩니다. 다음 로그 예시의 경우, data 매처를 사용해 맨 끝의 %를 삭제할 수 있습니다.

로그:

Usage: 24.3%

규칙:

MyParsingRule Usage\:\s+%{number:usage}%{data:ignore}

결과:

{
  "usage": 24.3,
  "ignore": "%"
}

ASCII 제어 문자

로그에 ASCII 제어 문자가 포함된 경우, 수집 시 직렬화됩니다. 이러한 문자는 Grok 파서 내에서 직렬화된 값으로 명시적으로 이스케이프하여 처리할 수 있습니다.

추가 자료

추가 유용한 문서, 링크 및 기사:

로그 파이프라인 빌드 및 수정 방법 알아보기학습 센터 로그 처리 방법 알아보기설명서 Datadog 모범 사례와 사용 팁: Grok 구문 분석을 사용해 로그에서 필드 추출비디오 로그 구문 분석 문제를 조사하는 방법FAQ 로그 구문 분석 - 모범 사례FAQ Datadog로 인덱싱된 로그 볼륨 제어설명서 로그 파이프라인 디버깅학습 센터