Watcher - Watcherの始め方（Getting started with Watcher） - 《Elasticsearchガイドv8.15》日本語

Watcherの始め方
ウォッチをスケジュールし、入力を定義する
条件を追加する
アクションを設定する
ウォッチを削除する
必要なセキュリティ権限
次に行うべきこと

Watcherの始め方

アラートを送信するためのウォッチを設定するには:

ウォッチをスケジュールし、入力を定義する。
条件を追加することで、アラートを送信する必要があるかどうかを確認します。
アクションを設定することで、条件が満たされたときにアラートを送信します。

ウォッチをスケジュールし、入力を定義する

ウォッチのスケジュールは、ウォッチがどのくらいの頻度でトリガーされるかを制御します。ウォッチの入力は、評価したいデータを取得します。

ログデータを定期的に検索し、その結果をウォッチに読み込むには、間隔スケジュールと検索入力を使用できます。たとえば、次のウォッチはlogsインデックスで10秒ごとにエラーを検索します:

Python

resp = client.watcher.put_watch(
   id="log_error_watch",
   trigger={
   "schedule": {
   "interval": "10s"
   }
   },
   input={
   "search": {
   "request": {
   "indices": [
   "logs"
   ],
   "body": {
   "query": {
   "match": {
   "message": "error"
   }
   }
   }
   }
   }
   },
)
print(resp)

Js

const response = await client.watcher.putWatch({
  id: "log_error_watch",
  trigger: {
   schedule: {
   interval: "10s",
   },
  },
  input: {
   search: {
   request: {
   indices: ["logs"],
   body: {
   query: {
   match: {
   message: "error",
   },
   },
   },
   },
   },
  },
});
console.log(response);

コンソール

PUT _watcher/watch/log_error_watch
{
  "trigger" : {
   "schedule" : { "interval" : "10s" }
  },
  "input" : {
   "search" : {
   "request" : {
   "indices" : [ "logs" ],
   "body" : {
   "query" : {
   "match" : { "message": "error" }
   }
   }
   }
   }
  }
}


	スケジュールは通常、あまり頻繁に実行されるように設定されています。この例では、間隔を10秒に設定しているため、ウォッチがトリガーされるのを簡単に確認できます。このウォッチは非常に頻繁に実行されるため、実験が終わったらウォッチを削除することを忘れないでください。

ウォッチの履歴を確認すると、ウォッチが10秒ごとにトリガーされていることがわかります。ただし、検索は結果を返さないため、ウォッチペイロードには何も読み込まれません。

たとえば、次のリクエストはウォッチ履歴から最後の10回のウォッチ実行（ウォッチ記録）を取得します:

Python

resp = client.search(
   index=".watcher-history*",
   pretty=True,
   sort=[
   {
   "result.execution_time": "desc"
   }
   ],
)
print(resp)

Ruby

response = client.search(
  index: '.watcher-history*',
  pretty: true,
  body: {
   sort: [
   {
   'result.execution_time' => 'desc'
   }
   ]
  }
)
puts response

Js

const response = await client.search({
  index: ".watcher-history*",
  pretty: "true",
  sort: [
   {
   "result.execution_time": "desc",
   },
  ],
});
console.log(response);

コンソール

GET .watcher-history*/_search?pretty
{
  "sort" : [
   { "result.execution_time" : "desc" }
  ]
}

条件を追加する

条件は、ウォッチに読み込まれたデータを評価し、アクションが必要かどうかを判断します。ログエラーをウォッチに読み込んだので、エラーが見つかったかどうかを確認する条件を定義できます。

たとえば、次の比較条件は、検索入力がヒットを返したかどうかを単純に確認します。

Python

resp = client.watcher.put_watch(
   id="log_error_watch",
   trigger={
   "schedule": {
   "interval": "10s"
   }
   },
   input={
   "search": {
   "request": {
   "indices": [
   "logs"
   ],
   "body": {
   "query": {
   "match": {
   "message": "error"
   }
   }
   }
   }
   }
   },
   condition={
   "compare": {
   "ctx.payload.hits.total": {
   "gt": 0
   }
   }
   },
)
print(resp)

Js

const response = await client.watcher.putWatch({
  id: "log_error_watch",
  trigger: {
   schedule: {
   interval: "10s",
   },
  },
  input: {
   search: {
   request: {
   indices: ["logs"],
   body: {
   query: {
   match: {
   message: "error",
   },
   },
   },
   },
   },
  },
  condition: {
   compare: {
   "ctx.payload.hits.total": {
   gt: 0,
   },
   },
  },
});
console.log(response);

コンソール

PUT _watcher/watch/log_error_watch
{
  "trigger" : { "schedule" : { "interval" : "10s" }},
  "input" : {
   "search" : {
   "request" : {
   "indices" : [ "logs" ],
   "body" : {
   "query" : {
   "match" : { "message": "error" }
   }
   }
   }
   }
  },
  "condition" : {
   "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
  }
}

| | 比較条件は、実行コンテキスト内の値と簡単に比較できるようにします。

この比較条件がtrueに評価されるためには、エラーを含むイベントをlogsインデックスに追加する必要があります。たとえば、次のリクエストはlogsインデックスに404エラーを追加します:

Python

resp = client.index(
   index="logs",
   document={
   "timestamp": "2015-05-17T18:12:07.613Z",
   "request": "GET index.html",
   "status_code": 404,
   "message": "Error: File not found"
   },
)
print(resp)

Ruby

response = client.index(
  index: 'logs',
  body: {
   timestamp: '2015-05-17T18:12:07.613Z',
   request: 'GET index.html',
   status_code: 404,
   message: 'Error: File not found'
  }
)
puts response

Js

const response = await client.index({
  index: "logs",
  document: {
   timestamp: "2015-05-17T18:12:07.613Z",
   request: "GET index.html",
   status_code: 404,
   message: "Error: File not found",
  },
});
console.log(response);

コンソール

POST logs/_doc
{
  "timestamp": "2015-05-17T18:12:07.613Z",
  "request": "GET index.html",
  "status_code": 404,
  "message": "Error: File not found"
}

このイベントを追加すると、次回ウォッチが実行されるとき、条件はtrueに評価されます。条件の結果は、ウォッチが実行されるたびにwatch_recordの一部として記録されるため、ウォッチ履歴を検索することで条件が満たされたかどうかを確認できます:

Python

resp = client.search(
   index=".watcher-history*",
   pretty=True,
   query={
   "bool": {
   "must": [
   {
   "match": {
   "result.condition.met": True
   }
   },
   {
   "range": {
   "result.execution_time": {
   "from": "now-10s"
   }
   }
   }
   ]
   }
   },
)
print(resp)

Ruby

response = client.search(
  index: '.watcher-history*',
  pretty: true,
  body: {
   query: {
   bool: {
   must: [
   {
   match: {
   'result.condition.met' => true
   }
   },
   {
   range: {
   'result.execution_time' => {
   from: 'now-10s'
   }
   }
   }
   ]
   }
   }
  }
)
puts response

コンソール

GET .watcher-history*/_search?pretty
{
  "query" : {
   "bool" : {
   "must" : [
   { "match" : { "result.condition.met" : true }},
   { "range" : { "result.execution_time" : { "from" : "now-10s" }}}
   ]
   }
  }
}

アクションを設定する

ウォッチ履歴にウォッチ記録を記録するのは良いことですが、Watcherの本当の力は、ウォッチ条件が満たされたときに何かを行うことができることです。ウォッチのアクションは、ウォッチ条件がtrueに評価されたときに何をするかを定義します。メールを送信したり、サードパーティのWebhookを呼び出したり、Elasticsearchインデックスにドキュメントを書き込んだり、標準のElasticsearchログファイルにメッセージを記録したりできます。

たとえば、次のアクションは、エラーが検出されたときにElasticsearchログにメッセージを書き込みます。

Python

resp = client.watcher.put_watch(
   id="log_error_watch",
   trigger={
   "schedule": {
   "interval": "10s"
   }
   },
   input={
   "search": {
   "request": {
   "indices": [
   "logs"
   ],
   "body": {
   "query": {
   "match": {
   "message": "error"
   }
   }
   }
   }
   }
   },
   condition={
   "compare": {
   "ctx.payload.hits.total": {
   "gt": 0
   }
   }
   },
   actions={
   "log_error": {
   "logging": {
   "text": "Found {{ctx.payload.hits.total}} errors in the logs"
   }
   }
   },
)
print(resp)

Js

const response = await client.watcher.putWatch({
  id: "log_error_watch",
  trigger: {
   schedule: {
   interval: "10s",
   },
  },
  input: {
   search: {
   request: {
   indices: ["logs"],
   body: {
   query: {
   match: {
   message: "error",
   },
   },
   },
   },
   },
  },
  condition: {
   compare: {
   "ctx.payload.hits.total": {
   gt: 0,
   },
   },
  },
  actions: {
   log_error: {
   logging: {
   text: "Found {{ctx.payload.hits.total}} errors in the logs",
   },
   },
  },
});
console.log(response);

コンソール

PUT _watcher/watch/log_error_watch
{
  "trigger" : { "schedule" : { "interval" : "10s" }},
  "input" : {
   "search" : {
   "request" : {
   "indices" : [ "logs" ],
   "body" : {
   "query" : {
   "match" : { "message": "error" }
   }
   }
   }
   }
  },
  "condition" : {
   "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
  },
  "actions" : {
   "log_error" : {
   "logging" : {
   "text" : "Found {{ctx.payload.hits.total}} errors in the logs"
   }
   }
  }
}

ウォッチを削除する


ウォッチを削除するには、[ウォッチ削除API](/read/elasticsearch-8-15/0bf431b3202d9620.md)を使用します:
#### Python
``````python
resp = client.watcher.delete_watch(
   id="log_error_watch",
)
print(resp)
`

Ruby

response = client.watcher.delete_watch(
  id: 'log_error_watch'
)
puts response

Js

const response = await client.watcher.deleteWatch({
  id: "log_error_watch",
});
console.log(response);

コンソール

DELETE _watcher/watch/log_error_watch

必要なセキュリティ権限

ユーザーがウォッチを作成および操作できるようにするには、watcher_adminセキュリティロールを割り当てます。ウォッチャー管理者は、ウォッチ、ウォッチ履歴、およびトリガーされたウォッチを表示することもできます。

ユーザーがウォッチとウォッチ履歴を表示できるようにするには、watcher_userセキュリティロールを割り当てます。ウォッチャーユーザーはウォッチを作成または操作することはできず、読み取り専用のウォッチ操作を実行することのみが許可されています。

次に行うべきこと

ウォッチの構造とウォッチライフサイクルに関する詳細はWatcherの仕組みを参照してください。
ウォッチの設定に関する他の例については例のウォッチを参照してください。
カスタムウォッチを構築するための出発点として使用できる追加のサンプルウォッチについては、Elastic Examplesリポジトリの例のウォッチを参照してください。