ログパーシング
ログパーサを使用すると、不規則な形のログをクエリが可能な構造化された形に変更できます。 WhaTapログモニタリングは、次の2つのタイプのパーサを提供します。
-
GROKパーサ：任意の形で収集されるログを正規表現とGROKを活用してパーシングします。
-
JSONパーサ：JSON形式で収集されるログをパーシングします。
共通の注意事項
-
同じカテゴリに複数のパーサが登録されている場合、最初にマッチングされるパーサのみが適用されます。
-
WhaTapはWhaTapサービスの安定性に影響を与えるパーサを無効にする場合があります。。
GROKパーサ
ログが不規則な形で収集される場合、GROKパーサを使用してログをパーシングできます。 GROKパターンは、named regular expressionsを提供し、正規表現をより簡単かつ便利に使用できます。
GROKパーサパターンの登録については、次の動画ガイドを参考にしてください。
GROKを開始する
GROKは2種類の文法を提供します。
-
%{SYNTAX:SEMANTIC}：GROKライブラリーが提供するパターンです。 named regular expressionsを活用してタグを抽出できます。 活用例は次のリンクを参照してください。-
SYNTAX：GROKが提供するnamed regular expressionsを指定します。
-
SEMANTIC：マッチングされる値に付ける名前を指定します。
ノートnamed regular expressions
GROKが提供するパターンです。 複雑な正規表現に名前を付けて使用できるよう、GROKが提供する機能です。
name regular expression WORD \b\w+\bSPACE \s*NOTSPACE \S+UUID [A-Fa-f0-9]{8}-(?:[A-Fa-f0-9]{4}-){3}[A-Fa-f0-9]{12}WhaTapで提供するすべてのnamed regular expressionsを確認したい場合は、次のリンクを参考にしてください。
-
-
(?<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+)
- 例1：
-
%{SYNTAX:SEMANTIC}活用の例
次は%{SYNTAX:SEMANTIC}を活用する例です。
[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な単語に置き換えると、次のように表現できます。
[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}?
- regular expression:
-
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)?)
- regular expression:
-
name:
DATA- regular expression:
.*?
- regular expression:
\[%{TIMESTAMP_ISO8601:date}\sGMT\]\[%{LOGLEVEL:level}\s\]\[%{DATA:caller}\]
上記の内容でパーシングすると、次のようにタグを抽出できます。 このようにGROKの%{SYNTAX:SEMANTIC}パターンは、複雑で長い正規表現を簡単に適用できる機能を提供します。
- 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}パターンだけでパーシングされない領域は次の通りです。
8 VirtualLog 20230808 02:01:00.000 {area=4, city=5} 56ms
該当ログの各部分をsemanticな単語に置き換えると、次のように表現できます。
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(\{、\,、\})で接続すると、次のようにパターンを適用できます。
(?<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
上記の内容でパーシングすると、次のようにタグを抽出できます。
- projectCode : 8
- logCategory : VirtualLog
- dexBuildStartTime : 20230808 02:01:00.000
- areaEnum : 4
- cityEnum : 5
- dexBuildElapsed : 56
GROKを適用する
ログ設定 > ログプライマリパーサ設定
-
GROKパターンパーサを適用するには、ログ設定メニューのログプライマリパーサ設定タブに移動します。
-
+ 追加するを選択した後パーサ入力欄でGROKパーサを選択します。
-
パターン登録ボタンを選択すると、右側にパターン登録とシミュレーション画面が表示されます。
-
パターンとログ入力後、シミュレーションボタンをクリックして、適用するパターンでパーシングに成功することを確認します。
パターン 例:
[%{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 -
シミュレーションの成功時シミュレーション結果と性能測定の結果を照会できます。
-
シミュレーション後、パターン適用ボタンをクリックすると、選択したパーサーに入力したパターンが適用されます。
-
パターン適用後、カテゴリとログ検出条件、パターンを入力します。
-
カテゴリ
ログカテゴリを選択します。 カテゴリは必須入力項目です。
-
ログ検出条件
-
条件を満たすログのみパーサが適用されます。
-
検索キーと検索値を選択するか、直接入力します。
-
ログ検出条件は、すべてのパーサが実行される前に適用されます。 つまり、パーサの結果として追加されるタグを使用できません。
-
-
カテゴリ
-
追加ボタンを選択してパーサを登録します。
-
ログパーサ一覧から該当パーサの優先順位を変更するか、活性化および修正、削除できます。
-
パーサーシミュレーション後、パターンを登録できます。
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)で終わる必要があります。
JSONパーサ
ログがJSONフォーマットで収集される場合、JSONパーサを使用して簡単かつ便利にパーシングできます。
JSONを適用する
ログ設定 > ログプライマリパーサ設定
-
JSONパターンパーサを適用するにはログ設定メニューのログプライマリパーサ設定タブに移動します。
-
+ 追加するを選択した後パーサ入力欄でJSONパーサを選択します。
-
パターン登録ボタンを選択すると、右側にパターン登録とシミュレーション画面が表示されます。
-
パターンとログ入力後、シミュレーションボタンをクリックして、適用するパターンでパーシングに成功することを確認します。
Example2023-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フォーマットの中でタグを生成しないキーを指定します。
-
-
シミュレーションの成功時シミュレーション結果と性能測定の結果を照会できます。
-
シミュレーション後、パターン適用ボタンをクリックすると、選択したパーサーに入力したパターンが適用されます。
-
パターン適用後、カテゴリとログ検出条件、パターンを入力します。
-
カテゴリ
ログカテゴリを選択します。 カテゴリは必須入力項目です。
-
ログ検出条件
-
条件を満たすログのみパーサが適用されます。
-
検索キーと検索値を選択するか、直接入力します。
-
ログ検出条件は、すべてのパーサが実行される前に適用されます。 つまり、パーサの結果として追加されるタグを使用できません。
-
-
カテゴリ
-
追加ボタンを選択してパーサを登録します。
-
ログパーサ一覧から該当パーサの優先順位を変更するか、活性化および修正、削除できます。
-
パーサを登録する前にシミュレーションを通じて登録するパターンが正常であるか確認できます。 GROKパーサ登録シミュレーションプロセスと同じです。 次の文書を参考にしてください。
JSONフォーマット活用例
{"host":"10.21.3.24","method":"POST","status":"200","url":"http://dev.whatap.io/yard/api/flush"}
上記のようなサンプルログが収集された場合パーサ 追加画面でJSONパーサを選択します。 複雑なパーシングロジックを作成する必要なく、ログ分析に必要なタグを次のように抽出できます。
- host : 10.21.3.24
- method : POST
- status : 200
- url : http://dev.whatap.io/yard/api/flush
JSONフ ォーマットを一部構成する時の活用例
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フォーマットで認識してからパーシングします。
- host : 10.21.3.24
- method : POST
- status : 200
- url : http://dev.whatap.io/yard/api/flush