ログパーシング

ログパーサを使用すると、不規則な形のログをクエリが可能な構造化された形に変更できます。 WhaTapログモニタリングは、次の2つのタイプのパーサを提供します。

• GROKパーサ：任意の形で収集されるログを正規表現とGROKを活用してパーシングします。

• JSONパーサ：JSON形式で収集されるログをパーシングします。

ノート

共通の注意事項

• 同じカテゴリに複数のパーサが登録されている場合、最初にマッチングされるパーサのみが適用されます。

• WhaTapはWhaTapサービスの安定性に影響を与えるパーサを非活性化にする権限を持ちます。

GROKパーサ

ログが不規則な形で収集される場合、GROKパーサを使用してログをパーシングできます。 GROKパターンは、named regular expressionsを提供し、正規表現をより簡単かつ便利に使用できます。

GROKパーサパターンの登録については、次の動画ガイドを参考にしてください。

GROKを開始する

GROKは2種類の文法を提供します。

1. %{SYNTAX:SEMANTIC}：GROKライブラリーが提供するパターンです。 named regular expressionsを活用してタグを抽出できます。 活用例は 次へを参照してください。

   • SYNTAX：GROKが提供するnamed regular expressionsを指定します。

   • SEMANTIC：マッチングされる値に付ける名前を指定します。

   ノート

   named regular expressions

   GROKが提供するパターンです。 複雑な正規表現に名前を付けて使用できるよう、GROKが提供する機能です。

   name	regular expression
   WORD	\b\w+\b
   SPACE	\s*
   NOTSPACE	\S+
   UUID	[A-Fa-f0-9]{8}-(?:[A-Fa-f0-9]{4}-){3}[A-Fa-f0-9]{12}

   WhaTapで提供するすべてのnamed regular expressionsを確認したい場合は、次のリンクを参考にしてください。

2. (?<SEMANTIC>REGX)：正規表現のnamed capturing group文法です。 正規表現を活用して、ユーザーの意図に合わせてタグを抽出できます。 活用例は次へを参照してください。

   • SEMANTIC：マッチングされる値に付ける名前を指定します。

   • REGX：マッチングに使用する正規表現を入力します。

   ノート

   named capturing group

   正規表現の文法です。

   • capturing group: 複数のトークンを1つにまとめて1つのマッチング単位で使用する機能を意味します。

   • named capturing group: capturing groupに名前を付けたものです。

   • 文字列マッチングの例を見てみましょう。 dev@whatap.io

     • 例1：(\w+)@(\w+\.\w+)
     • 例2：Eメールすべてのマッチング及びusernameとdomain追加マッチングすると(?<username>\w+)@(?<domain>\w+\.\w+)

%{SYNTAX:SEMANTIC}活用の例

次は%{SYNTAX:SEMANTIC}を活用する例です。

Sample log

[2023-08-08 02:02:30,101 GMT][INFO ][i.w.y.l.c.LogSinkDexScheduleThread.realProcess(159)] 8 VirtualLog 20230808 02:01:00.000 {area=4, city=5} 56ms

サンプルログを見て、各単語が意味する内容を推測できます。 各部分をsemanticな単語に置き換えると、次のように表現できます。

semantic replace

[date][logLevel][caller] projectCode logCategiry dexBuildStartTime {area=areaEnum, city=cityEnum} dexBuildElapsed

semanticな単語すべて、正規表現に書き換えできます。 GROKパーサを使用すると、事前に定義されたnamed regular expressionsを活用できます。 ここで使われたTIMESTAMP_ISO8601、LOGLEVEL、DATAは、GROKが提供するnamed regular expressionsです。 これらの値は、それぞれ次の正規表現に置き換えられてマッチングされます。

• name: TIMESTAMP_ISO8601

  • regular expression: %{YEAR}-%{MONTHNUM}-%{MONTHDAY}[T ]%{HOUR}:?%{MINUTE}(?::?%{SECOND})?%{ISO8601_TIMEZONE}?

• name: LOGLEVEL

  • regular expression: LOGLEVEL ([Aa]lert|ALERT|[Tt]race|TRACE|[Dd]ebug|DEBUG|[Nn]otice|NOTICE|[Ii]nfo|INFO|[Ww]arn?(?:ing)?|WARN?(?:ING)?|[Ee]rr?(?:or)?|ERR?(?:OR)?|[Cc]rit?(?:ical)?|CRIT?(?:ICAL)?|[Ff]atal|FATAL|[Ss]evere|SEVERE|EMERG(?:ENCY)?|[Ee]merg(?:ency)?)

• name: DATA

  • regular expression: .*?

GROK parsing pattern

\[%{TIMESTAMP_ISO8601:date}\sGMT\]\[%{LOGLEVEL:level}\s\]\[%{DATA:caller}\] 

上記の内容でパーシングすると、次のようにタグを抽出できます。 このようにGROKの%{SYNTAX:SEMANTIC}パターンは、複雑で長い正規表現を簡単に適用できる機能を提供します。

Tag extraction

- date : 2023-08-08 02:02:30,101
- caller : i.w.y.l.c.LogSinkDexScheduleThread.realProcess(159)
- level : LEVEL

(?<SEMANTIC>REGX)活用の例

named regular expressionsでマッチングされない部分は(?<SEMANTIC>REGX)パターンを使ってパーシングできます。 上記のサンプルログから%{SYNTAX:SEMANTIC}パターンだけでパーシングされない領域は次の通りです。

Unparsed area

8 VirtualLog 20230808 02:01:00.000 {area=4, city=5} 56ms

該当ログの各部分をsemanticな単語に置き換えると、次のように表現できます。

semantic replace

projectCode logCategiry dexBuildStartTime {area=areaEnum, city=cityEnum} dexBuildElapsed

このように不規則な形の文字列は、次のような(?<SEMANTIC>REGX)パターンを使ってパーシングできます。

サンプルログパーシングキーワード別にマッチングされる正規表現

パーシングキーワード	(?<SEMANTIC>REGX)
8	(?<projectCode>\d)
VirtualLog	(?<logCategory>\w*)
20230808 02:01:00.000	(?<dexBuildStartTime>\d{8}\s\d{2}:\d{2}:\d{2}\.\d{3})
area=4	area=(?<areaEnum>\d)
city=5	city=(?<cityEnum>\d)
56 ms	(?<dexBuildElapsed>\d{2})ms

正規表現の基本文法

文法	意味	別名
?	0 or 1	-
+	1 or more	-
*	0 or more	-
a{5}	exactly 5	-
\w	word character	[a-zA-Z_0-9]
\s	white space	-
.	any character except newline
[abc]	any of	-
[^abc]	not a,b, or c	-
[a-z]	character between a and z	-
[1-3[7-9]]	union (combining two or more character classes)	-
[1-6&&[3-9]]	intersection (共通集合)	-
[0-9&&[^2468]]	subtraction (差集合)	-
a{2,}	2 or more	-
a{1,3}	between 1 and 3	-
a+?	match as few as possible	-
{2,3}?	match as few as possible	-
(abc)	capturing group (複数の文字列をsingle unitで処理する)	-
\d	digit	[0-9]
\D	non-digit	[^0-9]
\W	non-word character	-
\S	non-white space	-

このようにパーシングされたキーワードをスペース(\s)と、特殊文字escape(\{、\,、\})で接続すると、次のようにパターンを適用できます。

GROK parsing pattern

(?<projectCode>\d)\s(?<logCategory>\w*)\s(?<dexBuildStartTime>\d{8}\s\d{2}:\d{2}:\d{2}\.\d{3})\s\{area=(?<areaEnum>\d),\scity=(?<cityEnum>\d)\}\s(?<dexBuildElapsed>\d{2})ms

上記の内容でパーシングすると、次のようにタグを抽出できます。

Tag extraction

- projectCode : 8
- logCategory : VirtualLog
- dexBuildStartTime : 20230808 02:01:00.000
- areaEnum : 4
- cityEnum : 5 
- dexBuildElapsed : 56

GROKを適用する

ログ設定 > ログプライマリパーサ設定

1. GROKパターンパーサを適用するには、ログ設定メニューのログプライマリパーサ設定タブに移動します。

2. + 追加するを選択した後パーサ入力欄でGROKパーサを選択します。

3. パターン登録ボタンを選択すると、右側にパターン登録とシミュレーション画面が表示されます。

4. パターンとログ入力後、シミュレーションボタンをクリックして、適用するパターンでパーシングに成功することを確認します。

   パターン 例: [%{TIMESTAMP_ISO8601:date}\sGMT][%{LOGLEVEL:level}\s][%{DATA:caller}]\s(?<projectCode>\d)\s(?<logCategory>\w*)\s(?<dexBuildStartTime>\d{8}\s\d{2}:\d{2}:\d{2}\.\d{3})\s\{area=(?<areaEnum>\d),\scity=(?<cityEnum>\d)\}\s(?<dexBuildElapsed>\d{2})ms

   ログ例: [2023-08-08 02:02:30,101 GMT][INFO ][i.w.y.l.c.LogSinkDexScheduleThread.realProcess(159)] 8 VirtualLog 20230808 02:01:00.000 {area=4, city=5} 56ms

5. シミュレーションの成功時シミュレーション結果と性能測定の結果を照会できます。

6. シミュレーション後、パターン適用ボタンをクリックすると、選択したパーサーに入力したパターンが適用されます。

7. パターン適用後、カテゴリとログ検出条件、パターンを入力します。

   

   • カテゴリ

     ログカテゴリを選択します。 カテゴリは必須入力項目です。

   • ログ検出条件

     • 条件を満たすログのみパーサが適用されます。

     • 検索キーと検索値を選択するか、直接入力します。

     • ログ検出条件は、すべてのパーサが実行される前に適用されます。 つまり、パーサの結果として追加されるタグを使用できません。

8. 追加ボタンを選択してパーサを登録します。

ノート

• ログパーサ一覧から該当パーサの優先順位を変更するか、活性化および修正、削除できます。

• パーサーシミュレーション後、パターンを登録できます。

ノート

GROKパーサの注意事項

• GROKパーサは%{SYNTAX:SEMANTIC}、%{SYNTAX:SEMANTIC}二つのパターンをサポートします。

• %{SYNTAX:SEMANTIC}パターンを使用する時、SEMANTICを必ず入力します。

• %{SYNTAX:SEMANTIC}パターンを使用する時、SEMANTICは一つのパーサの中でuniqueしなければなりません。

• (?<SEMANTIC>REGX)パターンを使用する時、SEMANTICは文字(a-z、A-Z)と数字(0-9)そして、指定された特殊文字(.、_、-)のみが使えます。

• SEMANTICは文字(a-z、A-Z)で始めなければなりません。

• SEMANTICは文字(a-z、A-Z)または数字(0-9)で終わる必要があります。

JSONパーサ

ログがJSONフォーマットで収集される場合、JSONパーサを使用して簡単かつ便利にパーシングできます。

JSONを適用する

ログ設定 > ログプライマリパーサ設定

1. JSONパターンパーサを適用するにはログ設定メニューのログプライマリパーサ設定タブに移動します。

2. + 追加するを選択した後パーサ入力欄でJSONパーサを選択します。

3. パターン登録ボタンを選択すると、右側にパターン登録とシミュレーション画面が表示されます。

4. パターンとログ入力後、シミュレーションボタンをクリックして、適用するパターンでパーシングに成功することを確認します。

   Example

   2023-08-08 02:43:28,615 -- {"host":"10.21.3.24","method":"POST","status":"200","url":"http://devote.whatap.io/yard/api/flush"} --

   例のログでPrefixとPostfixを--に指定し、Ignoreにurlを指定時host、method、status3つタグのみ生成します。

   • Prefix ログでJSONフォーマットが開始する場所を指定します。 ログ全体がJSONフォーマットの場合は、空の値に設定します。

   • Postfix ログでJSONフォーマットが終わる位置を指定します。 ログ全体がJSONフォーマットの場合は、空の値に設定します。

   • Ignore JSONフォーマットの中でタグを生成しないキーを指定します。

5. シミュレーションの成功時シミュレーション結果と性能測定の結果を照会できます。

   

6. シミュレーション後、パターン適用ボタンをクリックすると、選択したパーサーに入力したパターンが適用されます。

7. パターン適用後、カテゴリとログ検出条件、パターンを入力します。

   

   • カテゴリ

     ログカテゴリを選択します。 カテゴリは必須入力項目です。

   • ログ検出条件

     • 条件を満たすログのみパーサが適用されます。

     • 検索キーと検索値を選択するか、直接入力します。

     • ログ検出条件は、すべてのパーサが実行される前に適用されます。 つまり、パーサの結果として追加されるタグを使用できません。

8. 追加ボタンを選択してパーサを登録します。

ノート

• ログパーサ一覧から該当パーサの優先順位を変更するか、活性化および修正、削除できます。

• パーサを登録する前にシミュレーションを通じて登録するパターンが正常であるか確認できます。 GROKパーサ登録シミュレーションプロセスと同じです。 次の文書を参考にしてください。

JSONフォーマット活用例

Sample log

{"host":"10.21.3.24","method":"POST","status":"200","url":"http://devote.whatap.io/yard/api/flush"}

上記のようなサンプルログが収集された場合パーサ 追加画面でJSONパーサを選択します。 複雑なパーシングロジックを作成する必要なく、ログ分析に必要なタグを次のように抽出できます。

Tag extraction

- host : 10.21.3.24
- method : POST
- status : 200
- url : http://dev.whatap.io/yard/api/flush

JSONフォーマットを一部構成する時の活用例

Some JSON format sample log

2023-08-08 02:43:28,615 -- {"host":"10.21.3.24","method":"POST","status":"200","url":"http://devote.whatap.io/yard/api/flush"} --

もし、例のようにログの一部のみがJSONフォーマットで構成されている場合はPrefixとPostfixを指定してください。 WhaTapログモニタリングはPrefixとPostfix間の領域をJSONフォーマットで認識してからパーシングします。

Tag extraction

- host : 10.21.3.24
- method : POST
- status : 200
- url : http://dev.whatap.io/yard/api/flush