« 监测 API 更新监控 API »
Elastic 文档 ›Kibana 指南 [8.17] ›REST API ›监测 API

添加监控 API

编辑

添加监控 API

编辑

使用指定的属性创建一个新的监控。监控可以是以下类型之一：HTTP、TCP、ICMP 或 Browser。所需的字段和默认字段可能会因监控类型而异。

请求

编辑

POST <kibana 主机>:<端口>/api/synthetics/monitors

POST <kibana 主机>:<端口>/s/<space_id>/api/synthetics/monitors

先决条件

编辑

您必须在 可观测性 部分的 监测 功能中拥有 all 权限，请参阅 Kibana 功能权限。

请求体

编辑

请求体应包含要创建的监控的属性。所需的字段和默认字段取决于监控类型。

通用字段:

name
（必需，字符串）：监控的名称。
type
（必需，字符串）：监控类型（例如，http、tcp、icmp 或 browser）。
schedule

（可选，数字）：监控的计划时间（以分钟为单位）。支持的值为 1、3、5、10、15、30、60、120 和 240。

  • 对于 HTTP、TCP 和 ICMP 监控，默认值为 3 分钟。
  • 对于 Browser 监控，默认值为 10 分钟。
locations

（Array<SyntheticsLocationsType>）部署监控的位置。监控可以部署在多个位置，以便您可以检测这些位置的可用性和响应时间的差异。

要列出可用的位置，您可以

  • 使用部署的 Kibana URL 运行 {locations-command}[elastic-synthetics locations] 命令。
  • 转到 监测 → 管理，然后单击 创建监控。位置将列在位置中。
private_locations (Array<string>)

要将监控部署到的 私有位置。这些私有位置是指您托管和管理的位置，而 locations 由 Elastic 托管。您可以使用位置的名称指定私有位置。

要列出可用的私有位置，您可以

  • 使用部署的 Kibana URL 运行 {locations-command}[elastic-synthetics locations] 命令。
  • 转到 监测 → 设置，然后单击 私有位置。私有位置将列在表中。

您可以提供 locations 或 private_locations，或者两者都提供。至少需要一个。

enabled
（可选，布尔值，默认值：true）：监控是否启用。
tags
（可选，字符串数组）：标签数组。
alert
（可选，对象，默认值：{ status: { enabled: true }, tls: { enabled: true } }）：警报配置。
service.name
（可选，字符串）：APM 服务名称。
timeout
（可选，数字，默认值：16）：监控超时时间（以秒为单位），如果监控未在此时间内完成，则会失败。
namespace
（可选，字符串，默认值："default"）：namespace 字段应为小写且不包含空格。namespace 不得包含以下任何字符：*、\、/、?、"、<、>、|、空格、,、#、: 或 -
params
（可选，字符串）：监控参数。
retest_on_failure
（可选，布尔值，默认值：true）：在监控失败时启用或禁用重新测试。默认情况下，如果监控从“正常”变为“失败”，则会自动重新测试。如果重新测试的结果也是“失败”，则会创建错误，并且如果配置了警报，则会发送警报。然后，监控将根据定义的计划恢复运行。使用 retest_on_failure 可以减少与瞬时问题相关的噪声。

HTTP 监控字段:

url
（必需，字符串）：要监控的 URL。
ssl
（可选，对象）：用于 HTTPS 端点的 TLS/SSL 连接设置。如果您不指定设置，则使用系统默认设置。有关完整的 SSL 选项，请参阅 https://elastic.ac.cn/guide/en/beats/heartbeat/current/configuration-ssl.html。
max_redirects
（可选，数字，默认值：0）：要跟踪的最大重定向次数。
mode

（可选，字符串，默认值："any"）：监控的模式。可以是“all”或“any”。如果您正在使用 DNS 负载均衡器并且想要 ping 指定主机名的每个 IP 地址，则应使用 all。

  • any：监控仅 ping 主机名的一个 IP 地址。
  • all：监控 ping 主机名的所有可解析 IP。
ipv4
（可选，布尔值，默认值：true）：是否使用 ipv4 协议进行 ping。
ipv6
（可选，布尔值，默认值：true）：是否使用 ipv6 协议进行 ping。
username
（可选，字符串）：用于向服务器进行身份验证的用户名。凭据将随请求一起传递。
password
（可选，字符串）：用于向服务器进行身份验证的密码。凭据将随请求一起传递。
proxy_headers
（可选，对象）：在 CONNECT 请求期间发送到代理的附加标头。
proxy_url
（可选，字符串）：此监控要使用的代理的 URL。
response
（可选，对象）：控制将 HTTP 响应正文内容索引到 http.response.body.contents 字段。
response.include_body

（可选，布尔值，默认值：true）：控制将 HTTP 响应正文内容索引到 http.response.body.contents 字段。

  • include_body (“on_error” | “never” | “always”，默认值：on_error) 将 response.include_body 设置为以下列出的选项之一。

    • on_error：如果在检查期间遇到错误，则包含正文。这是默认值。
    • never：从不包含正文。
    • always：始终包含正文。
  • include_body_max_bytes （可选，数字，默认值：1024）设置 response.include_body_max_bytes 以控制存储的正文内容的最大大小。
check

（可选，对象）：检查请求设置。

  • request 要发送到远程主机的可选请求。在 check.request 下，指定以下选项

    • method (“HEAD” | “GET” | “POST” | “OPTIONS”)：要使用的 HTTP 方法。
    • headers （可选，对象）：要发送的附加 HTTP 标头的字典。默认情况下，监测会设置 User-Agent 标头以标识自身。

    • body （可选，字符串）：可选的请求正文内容。

      Example: This POSTs an x-www-form-urlencoded string to the endpoint
      {
  "check": {
    "request": {
      "method": "POST",
      "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
      },
      "body": "name=first&email=someemail%40someemailprovider.com"
    }
  }
}

  • response 预期的响应。在 check.response 下，指定以下选项

    • status 预期的状态代码列表。默认情况下，4xx 和 5xx 代码被视为失败。其他代码被视为正常。
    • headers （可选，对象）：预期的 HTTP 标头的字典。如果未找到标头，则检查失败。
    • body.positive：要匹配正文输出的正则表达式列表。只需要匹配单个表达式。示例：此监控检查响应正文中是否包含字符串 foo 或 Foo
    • body.negative：要以否定方式匹配正文输出的正则表达式列表。如果匹配单个表达式，则返回匹配失败。支持高达 100MiB 的 HTTP 响应正文。如果响应正文中完全没有 bar 或 Bar，则此监控检查匹配成功；如果响应正文中存在 bar 或 Bar，则检查匹配失败

    • json：当正文被解析为 JSON 时针对正文执行的表达式列表。正文大小必须小于或等于 100 MiB。

      • description （字符串）：检查的描述。
      • expression （字符串）：以下配置显示了当正文包含 JSON 时如何使用 gval 表达式检查响应

TCP 监控字段:

host
（必需，字符串）：要监控的主机；它可以是 IP 地址或主机名。主机可以使用冒号包含端口（例如，“example.com:9200”）。
ssl
（可选，对象）：用于 HTTPS 端点的 TLS/SSL 连接设置。如果您不指定设置，则使用系统默认设置。有关完整的 SSL 选项，请参阅 https://elastic.ac.cn/guide/en/beats/heartbeat/current/configuration-ssl.html。
check

要发送到远程主机的可选有效负载字符串和预期答案。如果未指定有效负载，则如果连接尝试成功，则假定端点可用。如果指定了 send 但没有 receive，则任何响应都被视为 OK。如果指定了 receive 但没有 send，则不发送有效负载，但客户端希望在连接时接收到“hello 消息”或“banner”形式的有效负载。

  • send （可选，字符串）：check.send: Hello World
  • receive （可选，字符串）：check.receive: Hello World
proxy_url
（可选，字符串）：用于连接到服务器时要使用的 SOCKS5 代理的 URL。该值必须是具有 socks5:// 方案的 URL。如果 SOCKS5 代理服务器需要客户端身份验证，则可以在 URL 中嵌入用户名和密码。使用代理时，主机名是在代理服务器上而不是在客户端上解析的。您可以通过设置 proxy_use_local_resolver 选项来更改此行为。
proxy_use_local_resolver
（可选，布尔值，默认值：false）：一个布尔值，用于确定主机名是在本地解析还是在代理服务器上解析。默认值为 false，表示名称解析在代理服务器上进行。

ICMP 监视器字段:

host
（必需，字符串）：要 ping 的主机。
等待
（可选，数字，默认值：1）：等待时间，以秒为单位。

浏览器监视器字段:

内联脚本
（必需，字符串）：内联脚本。
屏幕截图
（可选，字符串，默认值：“on”）：屏幕截图选项，可以是“on”、“off”或“only-on-failure”。
合成代理参数
（可选，数组）：合成代理 CLI 参数。
忽略 HTTPS 错误
（可选，布尔值，默认值：false）：是否忽略 HTTPS 错误。
Playwright 选项
（可选，对象）：Playwright 选项。

示例

编辑

以下是一些创建不同类型监视器的示例

HTTP 监视器：创建一个 HTTP 监视器来检查网站的可用性。

POST /api/synthetics/monitors
{
  "type": "http",
  "name": "Website Availability",
  "url": "https://example.com",
  "tags": ["website", "availability"],
  "locations": ["united_kingdom"]
}

TCP 监视器：创建一个 TCP 监视器来监控服务器的可用性。

POST /api/synthetics/monitors
{
  "type": "tcp",
  "name": "Server Availability",
  "host": "example.com",
  "private_locations": ["my_private_location"]
}

ICMP 监视器：创建一个 ICMP 监视器来执行 ping 检查。

POST /api/synthetics/monitors
{
  "type": "icmp",
  "name": "Ping Test",
  "host": "example.com",
  "locations": ["united_kingdom"]
}

浏览器监视器：创建一个浏览器监视器来检查网站。

POST /api/synthetics/monitors
{
  "type": "browser",
  "name": "Example journey",
  "inline_script": "step('Go to https://google.com.co', () => page.goto('https://www.google.com'))",
  "locations": ["united_kingdom"]
}
« 监测 API 更新监控 API »