メッセージ全体や未加工のイベントの特定の属性をパースするためのカスタム Grok ルールを作成できます。ベストプラクティスとして、Grok プロセッサー毎のパース規則は最大 10 で使用することが推奨されます。

Parse My Events をクリックして、基底のパイプラインを流れるイベントの 3 つのパースルールのセットを始動させます。そこから属性の名前を絞り込み、必要に応じて他のタイプのイベントに新しいルールを追加します。この機能を使用するには、対応するイベントがインデックス化され、実際に流入している必要があります。除外フィルターを一時的に無効にするか、サンプリングして、これを機能させることができます。

サンプルをクリックして選択すると、パースルールに対する評価が開始され、結果が画面の下に表示されます。

プロセッサーには最大 5 つのサンプルを保存できます。各サンプルの長さは最大 5000 文字となります。すべてのサンプルについて、Grok パーサーのパース規則のいずれかがそのサンプルに一致するかどうかのステータス (match または no match) を確認することができます。

Grok 構文

Grok パーサーは、半構造化テキストメッセージから属性を抽出します。Grok には、整数、IP アドレス、ホスト名などを解析するための再利用可能なパターンが含まれています。これらの値は、文字列として Grok パーサーに送られる必要があります。

パース規則は、%{MATCHER:EXTRACT:FILTER} 構文を使用して記述できます。

• Matcher: 期待する内容 (数値、単語、スペース以外など) を記述する規則 (または別のトークン規則への参照)。

• Extract (任意): Matcher と一致するテキストをキャプチャする対象を表す識別子。

• Filter (任意): 一致したテキストを変換するためのポストプロセッサー。

典型的な非構造化イベントの例

john connected on 11/08/2017 

これに次のパース規則を使用します。

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

処理後は、次のような構造化イベントが生成されます。

注:

• 1 つの Grok パーサーに複数のパース規則がある場合
  • 特定のイベントに一致する規則は 1 つだけです。上から下へ参照し、最初に一致した規則がパースを行う規則になります。
  • 各規則は上記のリストに定義されたパースを参照します。
• 同一の Grok パーサー内では同じ規則名を複数使用できません。
• 規則名には英数字、アンダースコア (_)、ピリオド (.) のみ使用できます。最初の文字は英数字でなければなりません。
• 値が null または空欄のプロパティは表示されません。
• 正規表現マッチャーは、文字列の先頭に一致するように暗黙の ^ を適用し、文字列の末尾に一致するように $ を適用します。
• 特定のイベントは、空白の大きなギャップを生成する可能性があります。改行と空白を表すには、\n と \s+ を使用します。

マッチャーとフィルター

以下に、Datadog でネイティブに実装されるすべてのマッチャーとフィルターを示します。

高度な設定

Grok プロセッサータイルの下部に、Advanced Settings セクションがあります。

特定のテキスト属性をパース

Extract from フィールドを使用して、デフォルトの message 属性ではなく、指定されたテキスト属性に Grok プロセッサを適用します。

たとえば、key-value としてパースされる必要のある command.line 属性を持つイベントを例に取ると、そのイベントは以下のようにパースできます。

ヘルパー規則を使用して複数のパース規則を再利用する

パース規則に使用するトークンを定義するには、Helper Rules フィールドを使用します。Helper Rules を使用すると、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

これは key-value コアフィルター keyvalue([separatorStr[, characterAllowList[, quotingStr[, delimiter]]]]) です。

• separatorStr: キーと値を区切るセパレーターを定義します。デフォルト =.
• characterAllowList: デフォルトの \\w.\\-_@ に加え、追加の非エスケープ値文字を定義します。引用符で囲まれていない値 (例: key=@valueStr) にのみ使用します。
• quotingStr: 引用符を定義し、デフォルトの引用符検出（<>、""、''）を置き換えます。
• delimiter: 異なる key-value ペアのセパレーターを定義します（すなわち、| は key1=value1|key2=value2の区切り文字です）。デフォルトは (通常のスペース)、, および ; です。

keyvalue などのフィルターを使用すると、keyvalue または logfmt 形式の属性に文字列をより簡単にマップできます。

イベント:

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

例:

rule %{data::keyvalue} 

パラメーターの名前はイベントに既に含まれているため、指定する必要はありません。 extract 属性 my_attribute を規則パターンに追加すると、次のようになります。

キーと値を区切るデフォルトのセパレーターが = 以外の場合は、セパレーターとともにパラメーターをパース規則に追加します。

イベント:

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 の例: 複数の引用文字列が定義されると、デフォルトの挙動が定義された引用文字に置き換えられます。 quotingStr で指定されている値にかかわらず、キーと値は引用文字列が使用されていなくても常に入力と一致します。 引用文字列が使用されている場合、引用符内の文字列がすべて抽出されるため、characterAllowList は無視されます。

イベント:

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

例:

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

結果:

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

注:

• 値が空 (key=) または null (key=null) の場合、出力される JSON に表示されません。
• data オブジェクトで keyvalue フィルターを定義する場合で、このフィルターが一致しない時は、空の JSON {} が返されます (例: 入力: key:=valueStr、パース規則: rule_test %{data::keyvalue("=")}、出力: {})。
• "" を quotingStr と定義すると、引用符のデフォルト設定が保持されます。

日付のパース

日付マッチャーは、タイムスタンプを EPOCH 形式 (millisecond 計測単位) に変換します。

¹  独自のローカライズを実行し、タイムスタンプが UTC _以外_の場合は、timezone パラメーターを使用します。 タイムゾーンとしてサポートされる形式は、以下になります。

• GMT、UTC、UT、Z
• +h、+hh、+hh:mm、-hh:mm、+hhmm、-hhmm、+hh:mm:ss、-hh:mm:ss、+hhmmss、-hhmmss 。対応する範囲は最大で +18:00 から -18:00 までです。
• UTC+、UTC-、GMT+、GMT-、UT+、UT- で始まるタイムゾーン。対応する範囲は最大で +18:00 から -18:00 までです。
• TZ データベースから取得されるタイムゾーン ID。詳細については、TZ データベース名を参照してください。

注: 日付をパースしても、その値は公式のイベント日付として設定されません。設定するには、後続のプロセッサーで イベント日付リマッパーを使用してください。

交互パターン

イベントの形式が 2 通りあり、そのうち 1 つの属性だけが異なる場合は、(<REGEX_1>|<REGEX_2>) による交互条件を使用して 1 つの規則を設定します。この規則は Boolean 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} 

結果

オプションの属性

必ずしも表示されない値がイベントに含まれることがあります。その場合は、()? を使用して属性抽出を任意にします。

イベント:

john 1234 connected on 11/08/2017 

規則の例

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

注: 任意のセクションで先頭の単語の後ろにスペースを含めると、規則は一致しません。

ネストされた 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} 

正規表現

イベント:

john_1a2b3c4 connected on 11/08/2017 

規則の例

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

リストから配列へ

リストを 1 つの属性の配列に取り出すには 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} 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 形式でログを記録することがあります。下の例は、パイプラインライブラリの 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: 異なる値の区切りに使用する区切り文字を定義します。1 文字のみ使用可能です。デフォルト: ,。注: TSV のタブ文字を表すには、separator に tab を使用します。
• quotingcharacter: 引用符を定義します。許可されるのは 1 文字だけです。デフォルトは " 。

注:

• 区切り文字を含む値は引用符で囲む必要があります。
• 引用符で囲まれた (引用符を含む) 値は引用符でエスケープする必要があります。たとえば、引用符を含む値における "" は " を意味します。
• ヘッダーに含まれるキー数と同じ個数の値がイベントに含まれていない場合、CSV パーサーは最初に出現する値とのマッチングを行います。
• 整数と浮動小数点数は、可能な場合自動でキャストされます。

イベント:

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 matcher を使用して、不要なテキストを破棄する

もし、必要な情報をパースした後のイベントで、それ以降のテキストは安全に破棄できるとわかっている場合、data matcher を使ってそれを行うことができます。以下のイベントの例では、data matcher を使って末尾の % を破棄することができます。

イベント:

Usage: 24.3% 

規則の例

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

Result:

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

ASCII 制御文字

イベントに ASCII 制御文字が含まれている場合、それは取り込み時にシリアル化されます。これは、grok パーサー内でシリアル化された値を明示的にエスケープすることで処理できます。