ログパーシング

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

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

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

ノート

共通の注意事項

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

• WhaTapはWhaTapサービスの安定性に影響を与えるパーサを無効にする場合があります。。

GROKパーサ

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

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 logCategory 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 logCategory 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は一つのパーサの中でユニークである必要があります。

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

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

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

GROK追加パターンの選択

GROKパーサのシミュレーション時に、基本パターン(WORD、NUMBER、IPなど)以外に特定のログ形式に合った追加パターンを選択できます。 Java、Nginx、MySQLなど32個のパターンタイプが11個のカテゴリにグループ化されて提供されます。

1. パーサのシミュレーション画面で**追加パターン (選択)**領域のドロップダウンをクリックしてください。

2. カテゴリ別にグループ化されたパターンタイプ一覧から、必要なパターンタイプを選択してください。 検索入力欄にパターンタイプ名または説明を入力して検索することもできます。

3. 選択したパターンタイプは、シミュレーション時に基本パターンとともにロードされます。

ノート

基本パターン(Core)は常に自動的に含まれます。 追加パターンの選択は任意です。

カテゴリ別パターンタイプ一覧

カテゴリ	パターンタイプ
Web Servers	haproxy, httpd, iis, nginx, squid
Application Servers & Frameworks	java, log4j, rails, ruby, springboot
Databases	mongodb, mysql, oracle, postgresql, redis
Cloud	aws
System & Infrastructure	docker, kubernetes, linux-syslog
Messaging & Search	elasticsearch, kafka
Network & Security	bind, bro, firewalls, junos, zeek
Mail	exim, postfix
Monitoring & Backup	bacula, mcollective, nagios
Build Tools	maven

活用例

Tomcat Catalina 8のログをパーシングするには、javaパターンタイプを追加で選択した後、%{CATALINA8_LOG}パターンを使用してください。

Sample log

31-Jul-2020 16:40:38 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Server version name: Apache Tomcat/8.5.57

GROK parsing pattern

%{CATALINA8_LOG}

Tag extraction

- log_timestamp : 31-Jul-2020 16:40:38
- log.level : INFO
- java.log.origin.thread.name : main
- java.log.origin.class.name : org.apache.catalina.startup.VersionLoggerListener
- log.origin.function : log
- log_message : Server version name: Apache Tomcat/8.5.57

パターン詳細表示

選択した追加パターンタイプにどのパターンが含まれているかを詳細画面で確認できます。 パターン定義(正規表現)とサンプルログを照会し、シミュレーションにすぐに適用できます。

追加パターンタイプを選択した後、選択されたパターンタイプのタグをクリックすると、右側に詳細画面が開きます。 詳細画面はシミュレーションフォームを隠さずに並んで表示されるため、パターン定義を確認しながらシミュレーションを進めることができます。

各パターン項目で次の機能を使用できます。

ボタン	機能	説明
サンプル	サンプルログ入力	該当パターンにマッチングする例ログをシミュレーションパーシングログ入力欄に自動的に入力します。
選択	パターン挿入	%{パターン名}形式でパターン入力欄に挿入します。 該当パターンタイプも自動的に選択されます。
コピー	クリップボードコピー	%{パターン名}形式をクリップボードにコピーします。

ノート

• パターン項目をクリックすると、パターン定義(正規表現)が展開されます。 複数のパターンを同時に展開して定義を比較できます。

• パターン定義に含まれる%{PATTERN:field}参照は、パターン名、フィールド名、リテラル文字がそれぞれ異なる色で区別されて表示されます。

• サンプルボタンで入力されたログでそのままシミュレーションを実行してパーシング結果を確認できます。

シミュレーションサンプルログの保存

シミュレーションに使用したログは、パーサ設定とともに自動的に保存されます。 パーサを修正する際に、以前に使用したサンプルログがシミュレーション画面に自動的に復元され、毎回ログを再入力する必要がありません。

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://dev.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://dev.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://dev.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