プロセッサリファレンス - Grok - 《Elasticsearchガイドv8.15》日本語

Grokプロセッサ
パイプラインでのGrokプロセッサの使用
カスタムパターン
複数の一致パターンの提供
RESTエンドポイントからのパターンの取得
Grokウォッチドッグ
Grokデバッグ
- Js

Grokプロセッサ

ドキュメント内の単一のテキストフィールドから構造化されたフィールドを抽出します。どのフィールドから一致したフィールドを抽出するか、また一致することを期待するgrokパターンを選択します。grokパターンは、再利用可能なエイリアス式をサポートする正規表現のようなものです。

このプロセッサには、多くの再利用可能なパターンがパッケージされています。

ログに一致するパターンを構築するのに助けが必要な場合は、Grokデバッガーツールが非常に便利です！Grokコンストラクタも便利なツールです。

パイプラインでのGrokプロセッサの使用

表23. Grokオプション

名前	必須	デフォルト	説明
`field`	はい	-	grok式解析に使用するフィールド
`patterns`	はい	-	一致して名前付きキャプチャを抽出するためのgrok式の順序付きリスト。一致するリスト内の最初の式を返します。
`pattern_definitions`	いいえ	-	現在のプロセッサで使用されるカスタムパターンを定義するパターン名とパターンタプルのマップ。一致する既存の名前のパターンは、事前に定義された定義を上書きします。
`ecs_compatibility`	いいえ	`disabled`	`disabled`または`v1`でなければなりません。`v1`の場合、プロセッサはElastic Common Schema (ECS)フィールド名を持つパターンを使用します。
`trace_match`	いいえ	false	trueの場合、`_ingest._grok_match_index`は一致したパターンが見つかった`patterns`のインデックスとともに、あなたの一致したドキュメントのメタデータに挿入されます。
`ignore_missing`	いいえ	false	`true`および`field`が存在しないか`null`の場合、プロセッサはドキュメントを変更せずに静かに終了します。
`description`	いいえ	-	プロセッサの説明。プロセッサの目的や構成を説明するのに便利です。
`if`	いいえ	-	プロセッサを条件付きで実行します。プロセッサを条件付きで実行するを参照してください。
`ignore_failure`	いいえ	`false`	プロセッサの失敗を無視します。パイプラインの失敗を処理するを参照してください。
`on_failure`	いいえ	-	プロセッサの失敗を処理します。パイプラインの失敗を処理するを参照してください。
`tag`	いいえ	-	プロセッサの識別子。デバッグやメトリクスに便利です。

ここに、提供されたパターンを使用してドキュメント内の文字列フィールドから構造化されたフィールドを抽出して名前を付ける例があります。

Python

resp = client.ingest.simulate(
   pipeline={
   "description": "...",
   "processors": [
   {
   "grok": {
   "field": "message",
   "patterns": [
   "%{IP:client} %{WORD:method} %{URIPATHPARAM:request} %{NUMBER:bytes:int} %{NUMBER:duration:double}"
   ]
   }
   }
   ]
   },
   docs=[
   {
   "_source": {
   "message": "55.3.244.1 GET /index.html 15824 0.043"
   }
   }
   ],
)
print(resp)

Ruby

response = client.ingest.simulate(
  body: {
   pipeline: {
   description: '...',
   processors: [
   {
   grok: {
   field: 'message',
   patterns: [
   '%{IP:client} %{WORD:method} %{URIPATHPARAM:request} %{NUMBER:bytes:int} %{NUMBER:duration:double}'
   ]
   }
   }
   ]
   },
   docs: [
   {
   _source: {
   message: '55.3.244.1 GET /index.html 15824 0.043'
   }
   }
   ]
  }
)
puts response

Js

const response = await client.ingest.simulate({
  pipeline: {
   description: "...",
   processors: [
   {
   grok: {
   field: "message",
   patterns: [
   "%{IP:client} %{WORD:method} %{URIPATHPARAM:request} %{NUMBER:bytes:int} %{NUMBER:duration:double}",
   ],
   },
   },
   ],
  },
  docs: [
   {
   _source: {
   message: "55.3.244.1 GET /index.html 15824 0.043",
   },
   },
  ],
});
console.log(response);

コンソール

POST _ingest/pipeline/_simulate
{
  "pipeline": {
   "description" : "...",
   "processors": [
   {
   "grok": {
   "field": "message",
   "patterns": ["%{IP:client} %{WORD:method} %{URIPATHPARAM:request} %{NUMBER:bytes:int} %{NUMBER:duration:double}"]
   }
   }
   ]
  },
  "docs":[
   {
   "_source": {
   "message": "55.3.244.1 GET /index.html 15824 0.043"
   }
   }
  ]
}

このパイプラインは、これらの名前付きキャプチャをドキュメント内の新しいフィールドとして挿入します。次のように:

コンソール-結果

{
  "docs": [
   {
   "doc": {
   "_index": "_index",
   "_id": "_id",
   "_version": "-3",
   "_source" : {
   "duration" : 0.043,
   "request" : "/index.html",
   "method" : "GET",
   "bytes" : 15824,
   "client" : "55.3.244.1",
   "message" : "55.3.244.1 GET /index.html 15824 0.043"
   },
   "_ingest": {
   "timestamp": "2016-11-08T19:43:03.850+0000"
   }
   }
   }
  ]
}

カスタムパターン

Grokプロセッサには、基本的なパターンのセットがあらかじめパッケージされています。これらのパターンには、必ずしもあなたが探しているものが含まれているわけではありません。パターンは非常に基本的な形式を持っています。各エントリには名前とパターン自体があります。


#### Js
``````js
{
  "description" : "...",
  "processors": [
   {
   "grok": {
   "field": "message",
   "patterns": ["my %{FAVORITE_DOG:dog} is colored %{RGB:color}"],
   "pattern_definitions" : {
   "FAVORITE_DOG" : "beagle",
   "RGB" : "RED|GREEN|BLUE"
   }
   }
   }
  ]
}
`

複数の一致パターンの提供

時には、1つのパターンではフィールドの潜在的な構造をキャプチャするには不十分です。あなたのお気に入りのペットの品種である猫または犬を含むすべてのメッセージに一致させたいと仮定しましょう。これを達成する1つの方法は、同じorの動作をキャプチャする非常に複雑な式の代わりに、一致できる2つの異なるパターンを提供することです。

ここに、simulate APIに対して実行されたそのような構成の例があります:

Python

resp = client.ingest.simulate(
   pipeline={
   "description": "parse multiple patterns",
   "processors": [
   {
   "grok": {
   "field": "message",
   "patterns": [
   "%{FAVORITE_DOG:pet}",
   "%{FAVORITE_CAT:pet}"
   ],
   "pattern_definitions": {
   "FAVORITE_DOG": "beagle",
   "FAVORITE_CAT": "burmese"
   }
   }
   }
   ]
   },
   docs=[
   {
   "_source": {
   "message": "I love burmese cats!"
   }
   }
   ],
)
print(resp)

Ruby

response = client.ingest.simulate(
  body: {
   pipeline: {
   description: 'parse multiple patterns',
   processors: [
   {
   grok: {
   field: 'message',
   patterns: [
   '%{FAVORITE_DOG:pet}',
   '%{FAVORITE_CAT:pet}'
   ],
   pattern_definitions: {
   "FAVORITE_DOG": 'beagle',
   "FAVORITE_CAT": 'burmese'
   }
   }
   }
   ]
   },
   docs: [
   {
   _source: {
   message: 'I love burmese cats!'
   }
   }
   ]
  }
)
puts response

Js

const response = await client.ingest.simulate({
  pipeline: {
   description: "parse multiple patterns",
   processors: [
   {
   grok: {
   field: "message",
   patterns: ["%{FAVORITE_DOG:pet}", "%{FAVORITE_CAT:pet}"],
   pattern_definitions: {
   FAVORITE_DOG: "beagle",
   FAVORITE_CAT: "burmese",
   },
   },
   },
   ],
  },
  docs: [
   {
   _source: {
   message: "I love burmese cats!",
   },
   },
  ],
});
console.log(response);

コンソール

POST _ingest/pipeline/_simulate
{
  "pipeline": {
  "description" : "parse multiple patterns",
  "processors": [
   {
   "grok": {
   "field": "message",
   "patterns": ["%{FAVORITE_DOG:pet}", "%{FAVORITE_CAT:pet}"],
   "pattern_definitions" : {
   "FAVORITE_DOG" : "beagle",
   "FAVORITE_CAT" : "burmese"
   }
   }
   }
  ]
},
"docs":[
  {
   "_source": {
   "message": "I love burmese cats!"
   }
  }
  ]
}

レスポンス:

コンソール-結果

{
  "docs": [
   {
   "doc": {
   "_index": "_index",
   "_id": "_id",
   "_version": "-3",
   "_source": {
   "message": "I love burmese cats!",
   "pet": "burmese"
   },
   "_ingest": {
   "timestamp": "2016-11-08T19:43:03.850+0000"
   }
   }
   }
  ]
}

両方のパターンは、適切な一致でフィールドpetを設定しますが、どのパターンが一致してフィールドを埋めたかを追跡したい場合はどうすればよいでしょうか？trace_matchパラメータを使用してこれを行うことができます。"trace_match": trueが構成された同じパイプラインの出力は次のとおりです:

コンソール-結果

{
  "docs": [
   {
   "doc": {
   "_index": "_index",
   "_id": "_id",
   "_version": "-3",
   "_source": {
   "message": "I love burmese cats!",
   "pet": "burmese"
   },
   "_ingest": {
   "_grok_match_index": "1",
   "timestamp": "2016-11-08T19:43:03.850+0000"
   }
   }
   }
  ]
}

上記のレスポンスでは、一致したパターンのインデックスが"1"であることがわかります。これは、patternsの2番目（インデックスはゼロから始まる）パターンが一致したことを意味します。

このトレースメタデータは、どのパターンが一致したかをデバッグするのに役立ちます。この情報は、インジェストメタデータに保存され、インデックスには登録されません。

RESTエンドポイントからのパターンの取得

Grokプロセッサには、プロセッサに含まれるパターンを取得するための独自のRESTエンドポイントがパッケージされています。

Python

resp = client.ingest.processor_grok()
print(resp)

Ruby

response = client.ingest.processor_grok
puts response

Js

const response = await client.ingest.processorGrok();
console.log(response);

コンソール

GET _ingest/processor/grok

上記のリクエストは、組み込みパターン辞書のキーと値の表現を含むレスポンスボディを返します。

Js

{
  "patterns" : {
   "BACULA_CAPACITY" : "%{INT}{1,3}(,%{INT}{3})*",
   "PATH" : "(?:%{UNIXPATH}|%{WINPATH})",
   ...
}

デフォルトでは、APIはレガシーGrokパターンのリストを返します。これらのレガシーパターンは、Elastic Common Schema (ECS)より前のもので、ECSフィールド名を使用していません。ECSフィールド名を抽出するパターンを返すには、オプションのv1クエリパラメータにv1を指定します。

Python

resp = client.ingest.processor_grok(
   ecs_compatibility="v1",
)
print(resp)

Ruby

response = client.ingest.processor_grok(
  ecs_compatibility: 'v1'
)
puts response

Js

const response = await client.ingest.processorGrok({
  ecs_compatibility: "v1",
});
console.log(response);

コンソール

GET _ingest/processor/grok?ecs_compatibility=v1

デフォルトでは、APIはディスクから読み取られる順序でパターンを返します。このソート順は、関連するパターンのグループを保持します。たとえば、Linux syslog行の解析に関連するすべてのパターンは一緒にグループ化されます。

オプションのブールsクエリパラメータを使用して、返されたパターンをキー名でソートすることもできます。

Python

resp = client.ingest.processor_grok(
   s=True,
)
print(resp)

Ruby

response = client.ingest.processor_grok(
  s: true
)
puts response

Js

const response = await client.ingest.processorGrok({
  s: "true",
});
console.log(response);

コンソール

GET _ingest/processor/grok?s

APIは次のレスポンスを返します。

Js

{
  "patterns" : {
   "BACULA_CAPACITY" : "%{INT}{1,3}(,%{INT}{3})*",
   "BACULA_DEVICE" : "%{USER}",
   "BACULA_DEVICEPATH" : "%{UNIXPATH}",
   ...
}

これは、組み込みパターンがバージョンごとに変更されるため、参照するのに役立ちます。

Grokウォッチドッグ

実行に時間がかかりすぎるgrok式は中断され、grokプロセッサは例外で失敗します。grokプロセッサには、grok式の評価が長すぎるかどうかを判断するウォッチドッグスレッドがあり、次の設定によって制御されます:

表24. Grokウォッチドッグ設定

名前	デフォルト	説明
`ingest.grok.watchdog.interval`	1s	最大許可実行時間を超えるgrok評価があるかどうかをチェックする頻度。
`ingest.grok.watchdog.max_execution_time`	1s	grok式評価の最大許可実行時間。

Grokデバッグ

grokパターンをデバッグするには、Grokデバッガーを使用することをお勧めします。そこから、サンプルデータに対してUIで1つまたは複数のパターンをテストできます。内部では、インジェストノードプロセッサと同じエンジンを使用しています。

さらに、Grokのデバッグログを有効にして、追加のメッセージがElasticsearchサーバーログに表示されるようにすることをお勧めします。

Js

PUT _cluster/settings
{
  "persistent": {
   "logger.org.elasticsearch.ingest.common.GrokProcessor": "debug"
  }
}