观察者操作

edit

当一个监视器的条件满足时,除非它正在被限流,否则它的动作会被执行。一个监视器可以执行多个动作。这些动作会一个接一个地执行,每个动作都是独立执行的。在执行动作时遇到的任何失败都会记录在动作结果和监视器历史记录中。

如果没有为监视器定义任何操作,则不会执行任何操作。 但是,仍然会在监视历史记录中写入一个watch_record

操作可以访问执行上下文中的有效负载。它们可以根据需要使用它来支持其执行。例如,有效负载可能作为模板化电子邮件正文的模型。

Watcher 支持以下操作:

确认和限流

edit

在监视执行期间,一旦满足条件,将根据配置的动作决定是否应进行限流。动作限流的主要目的是防止对同一监视执行过多的相同动作。

例如,假设你有一个监视器,用于检测应用程序日志条目中的错误。该监视器每五分钟触发一次,并在过去一小时内搜索错误。在这种情况下,如果有错误,监视器会在一段时间内被检查,并基于相同的错误多次执行其操作。结果是,系统管理员会收到关于同一问题的多次通知,这可能会令人烦恼。

为了解决这个问题,Watcher 支持基于时间的限流。您可以在操作配置中定义一个限流周期,以限制操作的执行频率。当您设置一个限流周期时,Watcher 会阻止在限流周期时间范围内(当前时间 - 限流周期)内重复执行该操作。

以下代码片段展示了上述场景中的一个监视器 - 将一个节流周期与email_administrator动作关联起来:

PUT _watcher/watch/error_logs_alert
{
  "metadata" : {
    "color" : "red"
  },
  "trigger" : {
    "schedule" : {
      "interval" : "5m"
    }
  },
  "input" : {
    "search" : {
      "request" : {
        "indices" : "log-events",
        "body" : {
          "size" : 0,
          "query" : { "match" : { "status" : "error" } }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 5 }}
  },
  "actions" : {
    "email_administrator" : {
      "throttle_period": "15m", 
      "email" : { 
        "to" : "sys.admino@host.domain",
        "subject" : "Encountered {{ctx.payload.hits.total}} errors",
        "body" : "Too many error in the system, see attached data",
        "attachments" : {
          "attached_data" : {
            "data" : {
              "format" : "json"
            }
          }
        },
        "priority" : "high"
      }
    }
  }
}

后续的 email_administrator 操作执行之间至少会有15分钟的间隔。

有关更多信息,请参阅电子邮件操作

您还可以在监视级别定义一个节流周期。监视级别的节流周期作为所有在监视中定义的操作的默认节流周期:

PUT _watcher/watch/log_event_watch
{
  "trigger" : {
    "schedule" : { "interval" : "5m" }
  },
  "input" : {
    "search" : {
      "request" : {
        "indices" : "log-events",
        "body" : {
          "size" : 0,
          "query" : { "match" : { "status" : "error" } }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 5 }}
  },
  "throttle_period" : "15m", 
  "actions" : {
    "email_administrator" : {
      "email" : {
        "to" : "sys.admino@host.domain",
        "subject" : "Encountered {{ctx.payload.hits.total}} errors",
        "body" : "Too many error in the system, see attached data",
        "attachments" : {
          "attached_data" : {
            "data" : {
              "format" : "json"
            }
          }
        },
        "priority" : "high"
      }
    },
    "notify_pager" : {
      "webhook" : {
        "method" : "POST",
        "host" : "pager.service.domain",
        "port" : 1234,
        "path" : "/{{watch_id}}",
        "body" : "Encountered {{ctx.payload.hits.total}} errors"
      }
    }
  }
}

后续操作执行之间至少会有15分钟的间隔(适用于email_administratornotify_pager操作)

如果在操作或监视级别未定义节流周期,则应用全局默认节流周期。最初,这设置为5秒。要更改全局默认值,请在elasticsearch.yml中配置xpack.watcher.execution.default_throttle_period设置:

xpack.watcher.execution.default_throttle_period: 15m

Watcher 还支持基于确认的限流。您可以使用 ack watch API 来确认一个监视,以防止在监视条件保持 true 时再次执行监视操作。这实际上是告诉 Watcher "我已收到通知并正在处理,请不要再通知我关于此错误的通知"。已确认的监视操作将保持在 acked 状态,直到监视的条件评估为 false。当这种情况发生时,操作的状态将变为 awaits_successful_execution

要确认一个操作,您可以使用ack watch API

POST _watcher/watch/<id>/_ack/<action_ids>

其中 是监视的 ID, 是你想要确认的操作 ID 的逗号分隔列表。要确认所有操作,请省略 actions 参数。

下图说明了在执行监视器时,为每个操作所做的限流决策:

action throttling

在 OpenJDK 中使用 SSL/TLS

edit

由于每个分发商可以自由选择如何打包OpenJDK,因此即使版本完全相同,OpenJDK分发版在不同的Linux发行版下可能包含不同的部分。

这可能会导致使用TLS的任何操作或输入出现问题,例如jirapagerdutyslackwebhook,因为缺少CA证书。 如果在编写连接到TLS端点的监视时遇到TLS错误, 您应该尝试升级到适用于您平台的最新可用OpenJDK发行版,如果这没有帮助,请尝试升级到Oracle JDK。

为数组中的每个元素运行一个操作

edit

您可以在操作中使用foreach字段,为数组中的每个元素触发配置的操作。

为了防止长时间运行的监视,您可以使用 max_iterations 字段来限制每个监视执行的最大运行次数。如果达到此限制,执行将优雅地停止。如果未设置,此字段默认为一百。

PUT _watcher/watch/log_event_watch
{
  "trigger" : {
    "schedule" : { "interval" : "5m" }
  },
  "input" : {
    "search" : {
      "request" : {
        "indices" : "log-events",
        "body" : {
          "query" : { "match" : { "status" : "error" } }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 0 } }
  },
  "actions" : {
    "log_hits" : {
      "foreach" : "ctx.payload.hits.hits", 
      "max_iterations" : 500,
      "logging" : {
        "text" : "Found id {{ctx.payload._id}} with field {{ctx.payload._source.my_field}}"
      }
    }
  }
}

日志记录语句将对每个返回的搜索命中执行。

为 Watcher 操作添加条件

edit

当触发器被触发时,其条件决定了是否执行触发器操作。在每个操作中,您还可以为每个操作添加一个条件。这些额外的条件使得单个警报可以根据各自的条

PUT _watcher/watch/log_event_watch
{
  "trigger" : {
    "schedule" : { "interval" : "5m" }
  },
  "input" : {
    "search" : {
      "request" : {
        "indices" : "log-events",
        "body" : {
          "size" : 0,
          "query" : { "match" : { "status" : "error" } }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 0 } }
  },
  "actions" : {
    "email_administrator" : {
      "email" : {
        "to" : "sys.admino@host.domain",
        "subject" : "Encountered {{ctx.payload.hits.total}} errors",
        "body" : "Too many error in the system, see attached data",
        "attachments" : {
          "attached_data" : {
            "data" : {
              "format" : "json"
            }
          }
        },
        "priority" : "high"
      }
    },
    "notify_pager" : {
      "condition": { 
        "compare" : { "ctx.payload.hits.total" : { "gt" : 5 } }
      },
      "webhook" : {
        "method" : "POST",
        "host" : "pager.service.domain",
        "port" : 1234,
        "path" : "/{{watch_id}}",
        "body" : "Encountered {{ctx.payload.hits.total}} errors"
      }
    }
  }
}

一个仅适用于notify_pager动作的条件,该条件限制其执行仅在条件成功时(在这种情况下至少有5次命中)。

观察者电子邮件操作

edit

使用 email 操作发送电子邮件通知。要发送电子邮件,您必须在 elasticsearch.yml配置至少一个电子邮件账户

电子邮件通知可以是纯文本或使用HTML进行样式化。您可以使用模板 包含来自监视执行负载的信息,并将整个监视负载附加到消息中。

查看电子邮件操作属性以了解支持的属性。任何在电子邮件操作定义中缺失的属性都会在电子邮件账户配置中查找。必需的属性必须在电子邮件操作定义或账户的email_defaults中设置。

配置电子邮件操作

edit

您在 actions 数组中配置电子邮件操作。特定于操作的属性使用 email 关键字指定。

例如,以下电子邮件操作使用模板在电子邮件正文中包含来自监视负载的数据:

"actions" : {
  "send_email" : { 
    "email" : { 
      "to" : "username@example.org", 
      "subject" : "Watcher Notification", 
      "body" : "{{ctx.payload.hits.total}} error logs found" 
    }
  }
}

操作的ID。

操作类型设置为email

一个或多个要发送电子邮件的地址。必须在操作定义或电子邮件账户配置中指定。

电子邮件的主题可以包含静态文本和 Mustache 模板

电子邮件的正文可以包含静态文本和 Mustache 模板。必须在操作定义或电子邮件账户配置中指定。

配置电子邮件附件

edit

您可以将来自任何HTTP服务的执行上下文有效负载或数据附加到电子邮件通知中。您可以配置的附件数量没有限制。

要配置附件,请为附加文件指定一个名称和附件类型:datahttpreportingdata 附件类型将执行上下文的有效负载附加到电子邮件消息中。http 附件类型使您能够发出 HTTP 请求并将响应附加到电子邮件消息中。配置 http 附件类型时,必须指定请求 URL。reporting 附件类型是一种特殊类型,用于包含来自 kibana 的 PDF 渲染仪表板。此类型会持续轮询 kibana 应用程序,以检查仪表板渲染是否完成,从而防止可能被防火墙或负载均衡器中断的长时间运行的 HTTP 连接。

"actions" : {
  "email_admin" : {
    "email": {
      "to": "John Doe <john.doe@example.com>",
      "attachments" : {
        "my_image.png" : { 
          "http" : { 
            "content_type" : "image/png",
            "request" : {
              "url": "http://example.org/foo/my-image.png" 
            }
          }
        },
        "dashboard.pdf" : {
          "reporting" : {
            "url": "http://example.org:5601/api/reporting/generate/dashboard/Error-Monitoring"
          }
        },
        "data.yml" : {
          "data" : {
            "format" : "yaml" 
          }
        }
      }
    }
  }
}

附件的ID,用作电子邮件附件中的文件名。

附件的类型及其具体配置。

用于检索附件的URL。

如果您未指定格式,数据附件默认使用JSON。

表84. http 附件类型属性

Name Description

content_type

设置电子邮件附件的内容类型。默认情况下,内容类型是从HTTP服务发送的响应中提取的。您可以显式指定内容类型,以确保在响应未指定内容类型或指定不正确的情况下,电子邮件中的类型设置正确。可选。

内联

配置为随附带方式 inline 发送的附件。这允许在HTML正文中使用嵌入式图像,这些图像在某些电子邮件客户端中显示。可选。默认为 false

请求

包含HTTP请求属性。至少,您必须指定url属性来配置服务端点和路径。请参阅Webhook操作属性以获取HTTP请求属性的完整列表。必需。

表85. 数据附件类型属性

Name Description

format

附加监视数据,相当于在监视配置中指定 attach_data。可能的值为 jsonyaml。如果未指定,默认为 json

表86. reporting 附件类型属性

Name Description

url

触发仪表板创建的URL

内联

配置为随附带方式 inline 发送的附件。这允许在HTML正文中使用嵌入式图像,这些图像在某些电子邮件客户端中显示。可选。默认为 false

retries

报告附件类型尝试定期轮询以接收创建的PDF。此配置了重试次数。默认为40。可以通过全局配置xpack.notification.reporting.retries来更改默认值。

区间

两次轮询尝试之间的等待时间。默认为 15s(这意味着,默认情况下,观察器尝试下载仪表板的时间为10分钟,四十次,每次15秒)。可以通过全局配置 xpack.notification.reporting.interval 来更改默认设置。

auth

请求的附加认证配置,详情请参见 使用观察器

代理

请求的附加代理配置。请参阅HTTP输入属性 了解如何配置这些值。

将报告附加到电子邮件

edit

您可以在 email 操作中使用 reporting 附件类型来自动生成 Kibana 报告并通过电子邮件分发。

请参阅自动化报告生成

电子邮件操作属性

edit
Name Required Default Description

账户

默认账户

用于发送电子邮件的电子邮件账户

-

发送电子邮件的电子邮件地址from字段可以包含Mustache模板,只要它解析为有效的电子邮件地址。

-

收件人的电子邮件地址to 字段可以包含 Mustache 模板 只要它解析为有效的电子邮件地址。

cc

-

抄送收件人的电子邮件地址cc 字段可以包含 Mustache 模板, 只要它解析为有效的电子邮件地址。

bcc

-

电子邮件地址bcc收件人。 bcc字段可以包含Mustache模板 只要它解析为有效的电子邮件地址。

reply_to

-

将在消息的 Reply-To 头中设置的电子邮件 地址reply_to 字段可以包含 Mustache 模板,只要它解析为有效的电子邮件地址。

主题

-

电子邮件的主题。主题可以是静态文本,也可以包含 Mustache templates

body

-

电子邮件的正文。当此字段保存一个字符串时,它将默认为电子邮件的文本正文。设置为对象以指定文本或HTML正文,或两者(使用下面的字段)

body.text

-

电子邮件的纯文本正文。正文可以是静态文本,也可以包含 Mustache 模板

body.html

-

电子邮件的HTML正文。正文可以是静态文本,也可以包含Mustache 模板。此正文将被净化以移除危险内容,例如脚本。可以通过在elasticsearch.yaml中设置xpack.notification.email.html.sanitization.enabled: false来禁用此行为。

优先级

-

此电子邮件的优先级。有效值为:最低正常最高。优先级可以包含一个 Mustache 模板,只要它解析为 其中一个有效值。

附件

-

将观察负载(data 附件)或从 HTTP 服务获取的文件(http 附件)附加到电子邮件。有关更多信息,请参阅 配置电子邮件附件

attach_data

指示是否应将监视执行数据附加到电子邮件中。您可以指定一个布尔值或一个对象。如果 attach_data 设置为 true,数据将作为 YAML 文件附加。此属性已弃用,请使用 attachments 属性添加 data 附件以附加监视负载。

attach_data.format

YAML

attach_data 指定为对象时,此字段控制附加数据的格式。支持的格式为 jsonyaml。此属性已弃用,请使用 attachments 属性添加 data 附件以附加监视负载。

Email Address
电子邮件地址可以包含两个可能的部分——地址本身和一个可选的个人名称,如RFC 822中所述。地址可以表示为形式为user@host.domain的字符串,或者表示为Personal Name 。您还可以将电子邮件地址指定为一个包含nameaddress字段的对象。
Address List
地址列表可以指定为一个数组:[ 'Personal Name ', 'user2@host.domain' ]

配置电子邮件账户

edit

Watcher 可以使用任何 SMTP 邮件服务发送电子邮件。电子邮件消息可以包含基本的 HTML 标签。您可以通过配置 HTML 清理选项来控制允许的标签组。

您可以在 elasticsearch.yml 文件的 xpack.notification.email 命名空间中配置 Watcher 用于发送电子邮件的账户。指定 SMTP 用户的密码安全地存储在 Elasticsearch 密钥库中。

如果您的电子邮件账户配置为需要两步验证,您需要生成并使用一个唯一的应用程序密码来从Watcher发送电子邮件。如果您使用主密码,身份验证将会失败。

Watcher 提供了三个电子邮件配置文件,用于控制 MIME 消息的结构:standard(默认)、gmailoutlook。这些配置文件适应了各种电子邮件系统对 MIME 标准的不同解释。如果您使用的是 Gmail 或 Outlook,我们建议使用相应的配置文件。如果您使用的是其他电子邮件系统,请使用 standard 配置文件。

有关配置 Watcher 以与不同电子邮件系统配合使用的更多信息,请参阅:

如果您配置了多个电子邮件账户,您必须配置一个默认账户,或者在email操作中指定使用哪个账户发送电子邮件。

xpack.notification.email:
  default_account: team1
  account:
    team1:
      ...
    team2:
      ...
从Gmail发送电子邮件
edit

使用以下电子邮件账户设置从 Gmail SMTP 服务发送电子邮件:

xpack.notification.email.account:
    gmail_account:
        profile: gmail
        smtp:
            auth: true
            starttls.enable: true
            host: smtp.gmail.com
            port: 587
            user: <username>

要存储账户SMTP密码,请使用keystore命令 (参见安全设置

bin/elasticsearch-keystore add xpack.notification.email.account.gmail_account.smtp.secure_password

如果您在尝试发送电子邮件时收到身份验证错误,提示您需要从网络浏览器继续登录过程,您需要配置Gmail以允许安全性较低的应用访问您的账户

如果为您的账户启用了两步验证,您必须生成并使用一个唯一的应用专用密码来从Watcher发送电子邮件。更多信息请参见使用应用专用密码登录

从Outlook.com发送电子邮件
edit

使用以下电子邮件账户设置从 Outlook.com SMTP 服务发送电子邮件操作:

xpack.notification.email.account:
    outlook_account:
        profile: outlook
        smtp:
            auth: true
            starttls.enable: true
            host: smtp-mail.outlook.com
            port: 587
            user: <email.address>

要存储账户SMTP密码,请使用密钥库命令 (参见安全设置

bin/elasticsearch-keystore add xpack.notification.email.account.outlook_account.smtp.secure_password

在发送电子邮件时,您必须提供一个发件人地址,可以是账户配置中的默认地址,也可以是监视器中电子邮件操作的一部分。

如果启用了双重验证,您需要使用一个唯一的应用程序密码。 有关更多信息,请参阅应用程序密码和双重验证

从 Amazon SES(简单电子邮件服务)发送电子邮件
edit

使用以下电子邮件账户设置从 Amazon Simple Email Service (SES) SMTP 服务发送电子邮件:

xpack.notification.email.account:
    ses_account:
        email_defaults:
            from: <email address of service account> 
        smtp:
            auth: true
            starttls.enable: true
            starttls.required: true
            host: email-smtp.us-east-1.amazonaws.com 
            port: 587
            user: <username>

在某些情况下,email_defaults.from 会由 Amazon SES 进行验证,以确保它是一个有效的本地电子邮件账户。

smtp.host 因地区而异。

要存储账户SMTP密码,请使用密钥库命令(参见安全设置

bin/elasticsearch-keystore add xpack.notification.email.account.ses_account.smtp.secure_password

您需要使用您的 Amazon SES SMTP 凭证通过 Amazon SES 发送电子邮件。更多信息,请参阅 获取您的 Amazon SES SMTP 凭证。您可能还需要在 AWS 上验证 您的电子邮件地址您的整个域名

从 Microsoft Exchange 发送电子邮件
edit

使用以下电子邮件账户设置从Microsoft Exchange发送电子邮件操作:

xpack.notification.email.account:
    exchange_account:
        profile: outlook
        email_defaults:
            from: <email address of service account> 
        smtp:
            auth: true
            starttls.enable: true
            host: <your exchange server>
            port: 587
            user: <email address of service account> 

一些组织配置Exchange以验证from字段是否为有效的本地电子邮件帐户。

许多组织支持使用您的电子邮件地址作为用户名,尽管如果您收到与身份验证相关的故障,最好与您的系统管理员确认。

要存储账户SMTP密码,请使用keystore命令 (参见安全设置

bin/elasticsearch-keystore add xpack.notification.email.account.exchange_account.smtp.secure_password
配置HTML清理选项
edit

The email action supports sending messages with an HTML body. 然而,出于安全原因,Watcher sanitizes the HTML.

您可以通过配置 elasticsearch.yml 文件中的 xpack.notification.email.html.sanitization.allowxpack.notification.email.html.sanitization.disallow 设置来控制允许或禁止哪些 HTML 功能。您可以指定单个 HTML 元素和 HTML 功能组。默认情况下,Watcher 允许以下功能:bodyhead_tables_links_blocks_formattingimg:embedded

例如,以下设置允许HTML包含表格和块元素,但不允许

标签。

xpack.notification.email.html.sanitization:
    allow: _tables, _blocks
    disallow: h4, h5, h6

要完全禁用清理,请将以下设置添加到 elasticsearch.yml

xpack.notification.email.html.sanitization.enabled: false

观察者 webhook 操作

edit

使用 webhook 操作向任何 Web 服务发送请求。webhook 操作支持 HTTP 和 HTTPS 连接。有关支持的属性,请参阅 Webhook 操作属性

配置webhook操作

edit

您在 actions 数组中配置 webhook 操作。特定于操作的属性使用 webhook 关键字指定。

以下代码片段展示了一个简单的webhook动作定义:

"actions" : {
  "my_webhook" : { 
    "transform" : { ... }, 
    "throttle_period" : "5m", 
    "webhook" : {
      "method" : "POST", 
      "host" : "mylisteningserver", 
      "port" : 9200, 
      "path": "/{{ctx.watch_id}}", 
      "body" : "{{ctx.watch_id}}:{{ctx.payload.hits.total}}" 
    }
  }
}

操作的ID

一个可选的转换,用于在执行webhook操作之前转换有效载荷

操作的可选限流周期(本例中为5分钟)

连接到主机时使用的HTTP方法

要连接的主机

要连接的端口

HTTP请求中使用的路径(URI)

发送请求时附带的正文

在向受保护的Web服务发送请求时,您可以使用基本身份验证。 例如,以下webhook操作在GitHub中创建一个新问题:

"actions" : {
  "create_github_issue" : {
    "transform": {
      "script": "return ['title':'Found errors in \\'contact.html\\'', 'body' : 'Found ' + ctx.payload.hits.total + ' errors in the last 5 minutes', 'assignee' : 'web-admin', 'labels' : ['bug','sev2']]"
    },
    "webhook" : {
      "method" : "POST",
      "url" : "https://api.github.com/repos/<owner>/<repo>/issues",
      "body": "{{#toJson}}ctx.payload{{/toJson}}",
      "auth" : {
        "basic" : {
          "username" : "<username>", 
          "password" : "<password>"
        }
      }
    }
  }
}

创建问题的用户的用户名和密码

默认情况下,用户名和密码都以明文形式存储在 .watches 索引中。当启用了 Elasticsearch 安全功能时,Watcher 可以在存储密码之前对其进行加密。

当向启用了Elasticsearch安全功能的集群提交请求时,您也可以使用基于PKI的身份验证。当您使用基于PKI的身份验证而不是HTTP基本认证时,您不需要在监视器本身中存储任何身份验证信息。要使用基于PKI的身份验证,您需要为Watcher配置SSL密钥设置,这些设置位于elasticsearch.yml中。

查询参数

edit

您可以使用 params 字段指定随请求一起发送的查询参数。 该字段仅包含一个对象,其中键作为参数名称,值作为参数值:

"actions" : {
  "my_webhook" : {
    "webhook" : {
      "method" : "POST",
      "host" : "mylisteningserver",
      "port" : 9200,
      "path": "/alert",
      "params" : {
        "watch_id" : "{{ctx.watch_id}}" 
      }
    }
  }
}

参数值可以包含模板字符串。

自定义请求头

edit

您可以使用 headers 字段指定随请求一起发送的请求头。 该字段仅包含一个对象,其中键作为头名称,值作为头值:

"actions" : {
  "my_webhook" : {
    "webhook" : {
      "method" : "POST",
      "host" : "mylisteningserver",
      "port" : 9200,
      "path": "/alert/{{ctx.watch_id}}",
      "headers" : {
        "Content-Type" : "application/yaml" 
      },
      "body" : "count: {{ctx.payload.hits.total}}"
    }
  }
}

头部值可以包含模板字符串。

Webhook 动作属性

edit
Name Required Default Description

scheme

http

连接方案。有效值为:httphttps

主机

-

要连接的主机。

端口

-

HTTP服务正在监听的端口。

路径

-

URL路径。路径可以是静态文本或包含Mustache 模板。URL查询字符串参数必须通过request.params属性指定。

方法

获取

HTTP 方法。有效值为:headgetpostputdelete

headers

-

HTTP 请求头。头值可以是静态文本,也可以包含 Mustache 模板

params

-

URL查询字符串参数。参数值可以是静态文本或包含Mustache 模板

auth

-

与身份验证相关的HTTP头。目前,仅支持基本身份验证。

body

-

HTTP 请求体。请求体可以是静态文本或包含 Mustache 模板。如果未指定,则发送空请求体。

proxy.host

-

连接到主机时使用的代理主机。

代理端口

-

连接到主机时使用的代理端口。

connection_timeout

10秒

设置http连接的超时时间。如果在该时间内无法建立连接,操作将超时并失败。

read_timeout

10秒

从http连接读取数据的超时时间。如果在该时间内未收到响应,操作将超时并失败。

url

-

用于将请求方案、主机、端口和路径指定为单个字符串的快捷方式。例如,http://example.org/foo/my-service

观察者索引操作

edit

使用 index 操作将数据索引到 Elasticsearch 中。 请参阅 Index action attributes 以了解支持的属性。

配置索引操作

edit

以下代码片段展示了一个简单的index动作定义:

"actions" : {
  "index_payload" : { 
    "condition": { ... }, 
    "transform": { ... }, 
    "index" : {
      "index" : "my-index-000001", 
      "doc_id": "my-id" 
    }
  }
}

操作的ID

一个可选的条件来限制动作执行

一个可选的转换,用于转换有效载荷并准备应索引的数据

数据将被写入的索引、别名或数据流

文档的可选 _id

索引操作属性

edit
Name Required Default Description

索引

*

-

要索引的索引、别名或数据流。也支持类似 的日期数学表达式。

*如果你动态设置了一个_index值,则不需要此参数。请参阅多文档支持

doc_id

-

文档的可选_id

op_type

索引

索引操作的 op_type。 必须是 indexcreate 之一。如果 index 是数据流,则必须是 create

execution_time_field

-

将存储/索引监视执行时间的字段。

timeout

60秒

等待索引 API 调用返回的超时时间。如果在该时间内没有返回响应,索引操作将超时并失败。此设置会覆盖默认的超时时间。

刷新

-

写请求的刷新策略可选设置

多文档支持

edit

与其他所有操作一样,您可以使用转换来替换当前执行上下文的载荷,从而更改最终索引的文档。

索引操作在其对特殊_doc有效负载字段的支持下,与转换配合良好。

在解析要索引的文档时,索引操作首先在载荷中查找_doc字段。如果未找到,则将载荷作为单个文档进行索引。

当存在_doc字段时,如果该字段包含一个对象,则该对象会被提取并作为一个单独的文档进行索引。如果该字段包含一个对象数组,则每个对象都被视为一个文档,并且索引操作会批量索引所有这些对象。

可以为每个文档添加一个_index_id值,以动态设置索引和已索引文档的ID。

以下代码片段展示了一个多文档的 index 操作定义:

"actions": {
  "index_payload": {
    "transform": {
      "script": """
      def documents = ctx.payload.hits.hits.stream()
        .map(hit -> [
          "_index": "my-index-000001", 
          "_id": hit._id, 
          "severity": "Sev: " + hit._source.severity 
        ])
        .collect(Collectors.toList());
      return [ "_doc" : documents]; 
      """
    },
    "index": {} 
  }
}

文档的索引

文档的可选 _id

一个新的 severity 字段,源自原始文档

负载 _doc 字段,这是一个文档数组

由于每个文档都通知了_index,这应该是空的

观察者日志记录操作

edit

使用 logging 操作将文本记录到标准的 Elasticsearch 日志中。有关支持的属性,请参阅 Logging action attributes

此操作主要用于开发和调试目的。

配置日志记录操作

edit

您在 actions 数组中配置日志记录操作。特定于操作的属性使用 logging 关键字指定。

以下代码片段展示了一个简单的日志记录操作定义:

"actions" : {
  "log" : { 
    "transform" : { ... }, 
    "logging" : {
      "text" : "executed at {{ctx.execution_time}}" 
    }
  }
}

操作的ID。

一个可选的转换,用于在执行logging操作之前转换有效载荷。

要记录的文本。

记录操作属性

edit
Name Required Default Description

文本

-

应记录的文本。可以是静态文本或包含 Mustache 模板

类别

xpack.watcher.actions.logging

文本将被记录的类别。

level

信息

日志级别。有效值为:errorwarninfodebugtrace

观察者 Slack 动作

edit

使用 slack 操作向 Slack 团队的频道或用户发送消息。要发送 Slack 消息,您需要在 elasticsearch.yml配置至少一个 Slack 账户

配置 Slack 操作

edit

您在 actions 数组中配置 Slack 操作。特定于操作的属性使用 slack 关键字指定。

以下代码片段展示了一个简单的Slack动作定义:

"actions" : {
  "notify-slack" : {
    "transform" : { ... },
    "throttle_period" : "5m",
    "slack" : {
      "message" : {
        "to" : [ "#admins", "@chief-admin" ], 
        "text" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)" 
      }
    }
  }
}

您想要发送消息的频道和用户。

消息的内容。

使用附件格式化 Slack 消息

edit

除了发送简单的基于文本的消息外,您还可以使用 Slack 的 附件机制来发送格式化的消息。Watcher 利用 Slack 附件,使您能够从执行上下文负载中动态填充模板消息。

以下代码片段展示了一个标准的消息附件:

"actions" : {
  "notify-slack" : {
    "throttle_period" : "5m",
    "slack" : {
      "account" : "team1",
      "message" : {
        "from" : "watcher",
        "to" : [ "#admins", "@chief-admin" ],
        "text" : "System X Monitoring",
        "attachments" : [
          {
            "title" : "Errors Found",
            "text" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
            "color" : "danger"
          }
        ]
      }
    }
  }
}

要定义一个从有效载荷动态填充的附件模板, 您在观察操作中指定dynamic_attachments。例如,动态 附件可以引用有效载荷中的直方图桶,并为每个桶构建一个 附件。

在以下示例中,watch 输入执行了一个带有日期直方图聚合的搜索,并触发了 Slack 动作:

  1. 将有效载荷转换为一个列表,其中列表中的每个项目都包含月份、该月的用户数量以及表示与该数量相关的情绪(危险或不良)的颜色。
  2. 定义一个附件模板,该模板引用由转换生成的列表中的项目。
"input" : {
  "search" : {
    "request" : {
      "body" : {
        "aggs" : {
          "users_per_month" : {
            "date_histogram" : {
              "field" : "@timestamp",
              "interval" : "month"
            }
          }
        }
      }
    }
  }
},
...
"actions" : {
  "notify-slack" : {
    "throttle_period" : "5m",
    "transform" : {
      "script" : {
        "source" : "['items': ctx.payload.aggregations.users_per_month.buckets.collect(bucket -> ['count': bucket.doc_count, 'name': bucket.key_as_string, 'color': bucket.doc_count < 100 ? 'danger' : 'good'])]",
        "lang" : "painless"
      }
    },
    "slack" : {
      "account" : "team1",
      "message" : {
        "from" : "watcher",
        "to" : [ "#admins", "@chief-admin" ],
        "text" : "System X Monitoring",
        "dynamic_attachments" : {
          "list_path" : "ctx.payload.items" 
          "attachment_template" : {
            "title" : "{{month}}", 
            "text" : "Users Count: {{count}}",
            "color" : "{{color}}"
          }
        }
      }
    }
  }
}

由操作的转换生成的列表。

参数占位符指的是由转换生成的列表中每个项目的属性。

Slack 操作属性

edit
Name Required Description

message.from

在 Slack 消息中显示的发送者名称。 覆盖传入 webhook 的配置名称。

message.to

您希望发送消息的频道和用户。频道名称必须以 # 开头,用户名称必须以 @ 开头。接受字符串值或字符串值数组。

message.icon

在 Slack 消息中显示的图标。覆盖传入 webhook 的配置图标。接受一个公共 URL 到图像。

message.text

消息内容。

message.attachments

Slack 消息附件。消息附件使您能够创建格式更丰富的消息。指定的数组定义在 Slack 附件文档中。

message.dynamic_attachments

可以根据当前监视负载动态填充的 Slack 消息附件。更多信息,请参阅 使用附件格式化 Slack 消息

proxy.host

要使用的代理主机(仅在与 proxy.port 结合使用时)

代理端口

要使用的代理端口(仅在与 proxy.host 结合使用时)

配置 Slack 账户

edit

您可以在 elasticsearch.yml 文件的 xpack.notification.slack 命名空间中配置 Watcher 用于与 Slack 通信的账户。

您需要一个具有传入Webhooks功能的Slack应用程序来配置Slack账户。使用生成的webhook URL在Elasticsearch中设置您的Slack账户。

要配置一个 Slack 账户,至少需要在 Elasticsearch 密钥库中指定账户名称和 webhook URL(参见 安全设置):

bin/elasticsearch-keystore add xpack.notification.slack.account.monitoring.secure_url

您不能再使用 elasticsearch.yml 设置来配置 Slack 账户。 请改用 Elasticsearch 的安全 密钥库 方法。

您可以为 Slack 通知属性指定默认值:

xpack.notification.slack:
  account:
    monitoring:
      message_defaults:
        from: x-pack
        to: notifications
        icon: http://example.com/images/watcher-icon.jpg
        attachment:
          fallback: "X-Pack Notification"
          color: "#36a64f"
          title: "X-Pack Notification"
          title_link: "https://www.elastic.co/guide/en/x-pack/current/index.html"
          text: "One of your watches generated this notification."
          mrkdwn_in: "pretext, text"

要通知多个频道,请在 Slack 中为每个频道创建一个 webhook URL,并在 Elasticsearch 中创建多个 Slack 账户(每个 webhook URL 对应一个账户)。

如果你配置了多个 Slack 账户,你需要配置一个默认账户,或者在 slack 操作中指定通知应发送到的账户。

xpack.notification.slack:
  default_account: team1
  account:
    team1:
      ...
    team2:
      ...

Watcher PagerDuty 操作

edit

使用PagerDuty操作在PagerDuty中创建事件。要创建PagerDuty事件,您必须在elasticsearch.yml配置至少一个PagerDuty账户

配置PagerDuty操作

edit

您在 actions 数组中配置 PagerDuty 操作。特定于操作的属性使用 pagerduty 关键字指定。

以下代码片段展示了一个简单的PagerDuty操作定义:

"actions" : {
  "notify-pagerduty" : {
    "transform" : { ... },
    "throttle_period" : "5m",
    "pagerduty" : {
      "description" : "Main system down, please check!" 
    }
  }
}

消息的描述

向PagerDuty事件添加元信息

edit

为了给PagerDuty事件提供更多上下文,您可以附加有效负载以及上下文数组到操作中。

"actions" : {
  "notify-pagerduty" : {
    "throttle_period" : "5m",
    "pagerduty" : {
      "account" : "team1",
      "description" : "Main system down, please check! Happened at {{ctx.execution_time}}",
      "attach_payload" : true,
      "client" : "/foo/bar/{{ctx.watch_id}}",
      "client_url" : "http://www.example.org/",
      "contexts" : [
        {
          "type": "link",
          "href": "http://acme.pagerduty.com"
        },{
          "type": "link",
          "href": "http://acme.pagerduty.com",
          "text": "View the incident on {{ctx.payload.link}}"
        }
      ]
    }
  }
}

Pagerduty 操作属性

edit
Name Required Description

账户

要使用的账户,回退到默认账户。 该账户需要一个service_api_key属性。

尽管下面的一些属性名称与PagerDuty“Events API v1”参数名称匹配,但最终使用的是“Events API v2”API,并通过适当转换属性来实现。

表87. Pagerduty事件触发事件属性

Name Required Description

描述

此事件的简要描述

事件类型

要发送的事件类型。必须是以下之一:triggerresolveacknowledge。默认为 trigger

incident_key

PagerDuty 端的事件键,也用于去重,并允许解决或确认事件。

客户端

触发事件的客户端名称,即 Watcher Monitoring

client_url

一个客户端URL,访问以获取更多详细信息。

attach_payload

如果设置为true,则有效载荷将作为详细信息附加到API调用中。默认为false

上下文

一个对象数组,允许您提供额外的链接或图像,以便为触发器提供更多上下文。

proxy.host

要使用的代理主机(仅在与 proxy.port 结合使用时)

代理端口

要使用的代理端口(仅在与 proxy.host 结合使用时)

您可以使用xpack.notification.pagerduty.event_defaults.*属性为整个服务配置上述值的默认值,也可以使用xpack.notification.pagerduty.account.your_account_name.event_defaults.*为每个账户配置默认值。

所有这些对象都支持模板功能,因此您可以将上下文和有效负载中的数据用作所有字段的一部分。

表88. Pagerduty事件触发上下文属性

Name Required Description

类型

其中一个 linkimage

href

是/否

一个包含更多信息的链接。如果类型是link,则必须存在;如果类型是image,则是可选的

src

用于image类型的src属性。

配置 PagerDuty 账户

edit

您在 elasticsearch.yml 文件的 xpack.notification.pagerduty 命名空间中配置 Watcher 用于与 PagerDuty 通信的账户。

要配置PagerDuty账户,您需要您希望发送通知的PagerDuty服务的API集成密钥。要获取密钥:

  1. 以账户管理员身份登录到 pagerduty.com
  2. 转到 服务 并选择您希望目标的 PagerDuty 服务。
  3. 点击 集成 标签,并添加一个 Events API V2 集成(如果尚不存在)。
  4. 复制 API 集成密钥以供下面使用。

要在密钥库中配置PagerDuty账户,您必须指定账户名称和集成密钥(参见安全设置):

bin/elasticsearch-keystore add xpack.notification.pagerduty.account.my_pagerduty_account.secure_service_api_key

在7.0.0中已弃用。

在YAML文件中或通过集群更新设置存储服务API密钥仍然受支持,但应使用密钥库设置。

您还可以为 PagerDuty事件属性 指定默认值:。

xpack.notification.pagerduty:
  account:
    my_pagerduty_account:
      event_defaults:
        description: "Watch notification"
        incident_key: "my_incident_key"
        client: "my_client"
        client_url: http://www.example.org
        event_type: trigger
        attach_payload: true

如果您配置了多个PagerDuty账户,您需要设置一个默认账户,或者在pagerduty操作中指定事件应发送到的账户。

xpack.notification.pagerduty:
  default_account: team1
  account:
    team1:
      ...
    team2:
      ...

观察者 Jira 动作

edit

使用 jira 操作在 Atlassian 的 Jira 软件中创建问题。 要创建问题,您需要在 elasticsearch.yml配置至少一个 Jira 账户

配置Jira操作

edit

您在 actions 数组中配置 Jira 操作。特定于操作的属性使用 jira 关键字指定。

以下代码片段展示了一个简单的Jira操作定义:

"actions" : {
  "create-jira-issue" : {
    "transform" : { ... },
    "throttle_period" : "5m",
    "jira" : {
      "account" : "integration-account", 
      "fields" : {
          "project" : {
            "key": "PROJ" 
          },
          "issuetype" : {
            "name": "Bug" 
          },
          "summary" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes", 
          "description" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)", 
          "labels" : ["auto"], 
          "priority" : {
            "name" : "High" 
          }
      }
    }
  }
}

elasticsearch.yml 中配置的 Jira 账户名称。

将在其中创建问题的Jira项目的关键。

问题类型的名称。

Jira问题的摘要。

Jira问题的描述。

要应用于Jira问题的标签。

Jira问题的优先级。

Jira 操作属性

edit

根据Jira项目的配置方式,问题可以具有许多不同的字段和值。因此,jira 操作可以在其 issue 字段中接受任何类型的子字段。这些字段将在调用Jira的创建问题API时直接使用,允许使用任何类型的自定义字段。

在 Jira 中创建问题时,始终需要 project.key(或 project.id)、issuetype.name(或 issuetype.id)和 issue.summary

Name Required Description

账户

用于发送消息的Jira账户。

proxy.host

要使用的代理主机(仅在与 proxy.port 结合使用时)

代理端口

要使用的代理端口(仅在与 proxy.host 结合使用时)

fields.project.key

将在其中创建问题的Jira项目的键。如果已知项目的标识符,可以用issue.project.id替换。

fields.issuetype.name

一个用于标识问题类型的名称。Jira 提供了默认的问题类型,如 BugTaskStoryNew Feature 等。如果已知类型的标识符,可以用 issue.issuetype.id 替换。

fields.summary

问题的摘要(或标题)。

fields.description

问题的描述。

fields.labels

要应用于Jira问题的标签。

fields.priority.name

Jira问题的优先级。Jira提供默认的优先级级别。

fields.assignee.name

要分配问题的用户名称。

fields.reporter.name

识别为问题报告者的用户名称。默认为用户账户。

fields.environment

与问题相关的环境名称。

fields.customfield_XXX

问题自定义字段XXX(例如:"customfield_10000": "09/Jun/81")

配置Jira账户

edit

您可以在 elasticsearch.yml 文件的 xpack.notification.jira 命名空间中配置 Watcher 用于与 Jira 通信的账户。

Watcher 支持 Jira Software 的基本身份验证。要配置 Jira 账户,您需要指定(参见 安全设置):

bin/elasticsearch-keystore add xpack.notification.jira.account.monitoring.secure_url
bin/elasticsearch-keystore add xpack.notification.jira.account.monitoring.secure_user
bin/elasticsearch-keystore add xpack.notification.jira.account.monitoring.secure_password

在配置文件或集群设置中存储敏感数据(urluserpassword)是不安全的,并且已被弃用。请改用 Elasticsearch 的安全 keystore 方法。

为了避免凭证在网络上以明文传输,Watcher 将拒绝基于纯文本 HTTP 协议的 url 设置,例如 http://internal-jira.elastic.co。此默认行为可以通过显式的 allow_http 设置来禁用:

字段 url 也可以包含一个路径,用于创建问题。默认情况下,这是 /rest/api/2/issue。如果您也设置了此路径,请确保这是创建问题的端点的完整路径。

xpack.notification.jira:
  account:
    monitoring:
      allow_http: true

强烈建议仅使用带有安全HTTPS协议的基本身份验证。

您还可以为 Jira issues指定默认值:

xpack.notification.jira:
  account:
    monitoring:
      issue_defaults:
        project:
          key: proj
        issuetype:
          name: Bug
        summary: "X-Pack Issue"
        labels: ["auto"]

如果你配置了多个 Jira 账户,你需要配置一个默认账户,或者在 jira 操作中指定通知应发送的账户。

xpack.notification.jira:
  default_account: team1
  account:
    team1:
      ...
    team2:
      ...