« 监控私有网络上的资源 过滤监控 »
Elastic 文档 ›Elastic 可观测性 [8.14] ›合成监控

使用 Synthetics CLI

编辑

使用 Synthetics CLI编辑

@elastic/synthetics编辑

Synthetics 应用程序使用 @elastic/synthetics Node.js 库来运行合成浏览器测试并报告测试结果。该库还提供了一个 CLI 来帮助您搭建、本地开发/运行测试以及将测试推送到 Kibana。

npx @elastic/synthetics [options] [files] [dir]

您不需要使用大多数命令行标志——它们纯粹是为了与 Synthetics 应用程序交互而实现的。但是，您可能会发现一些有用的标志

--match <string>
运行名称或标签与给定 glob 模式匹配的测试。
--tags Array<string>
运行与给定 glob 模式匹配的给定标签的测试。
--pattern <string>
用于匹配当前工作目录中旅程文件的正则表达式模式。默认值为 /*.journey.(ts|js)$/，它匹配以 .journey.ts 或 .journey.js 结尾的文件。
--params <jsonstring>

定义测试所需的任何变量的 JSON 对象。在 使用参数和密钥 中了解更多信息。

传递的参数将与 synthetics.config.js 文件 中定义的参数合并。通过 CLI 定义的参数优先。

--playwright-options <jsonstring>

用于向代理传递自定义 Playwright 选项的 JSON 对象。有关相关 Playwright 选项的更多详细信息，请参阅 配置文档。

传递的选项将与 synthetics.config.js 文件 中定义的 Playwright 选项合并。通过 CLI 定义的选项优先。

--screenshots <on|off|only-on-failure>

控制是否在每个步骤结束时捕获屏幕截图。选项包括 'on'、'off' 或 'only-on-failure'。

这也可以在配置文件中使用 monitor.screenshot 设置。通过 CLI 定义的值优先。

-c, --config <string>
配置文件的路径。默认情况下，测试运行器在当前目录中查找 synthetics.config.(js|ts) 文件。Synthetics 配置提供选项来配置测试的运行方式以及推送到 Kibana 的方式。允许的选项在 配置文件 中描述。
--reporter <json|junit|buildkite-cli|default>
json、junit、buildkite-cli 或 default 之一。使用 JUnit 或 Buildkite 报告器为 CI 系统提供易于解析的输出。
--inline
不从文件读取，而是 cat 内联脚本旅程并通过 stdin 传递它们。例如，cat path/to/file.js | npx @elastic/synthetics --inline。
--no-throttling

不应用节流。

节流也可以在配置文件中使用 monitor.throttling 禁用。通过 CLI 定义的值优先。

基于浏览器的监控的网络节流已禁用。有关更多详细信息，请参阅此 文档。

--no-headless

以无头模式运行浏览器。

这与通过运行 --playwright-options '{"headless": false}' 将 Playwright 的 headless 选项 设置为 false 相同。

无头模式仅应在本地使用，以便查看浏览器并直接与 DOM 元素交互以进行测试。不要尝试在通过 Elastic 的全局托管测试基础设施或私有位置运行时以无头模式运行，因为这不受支持。

-h, --help
显示 npx @elastic/synthetics 命令的帮助信息。

用于过滤的 --pattern、--tags 和 --match 标志仅在您在本地运行合成测试或将它们推送到 Kibana 时受支持。过滤不支持任何其他子命令，例如 init 和 locations。

为了在本地调试合成测试，您可以设置环境变量 DEBUG=synthetics npx @elastic/synthetics 来捕获 Synthetics 代理日志。

@elastic/synthetics init编辑

使用 Elastic Synthetics 搭建一个新项目。

这将创建一个模板 Node.js 项目，其中包含 synthetics 代理、必需的依赖项、synthetics 配置文件以及示例浏览器和轻量级监控文件。这些文件可以被编辑，然后推送到 Kibana 以创建监控。

npx @elastic/synthetics init <name-of-project>

在 创建项目 中详细了解模板项目中包含的内容。

@elastic/synthetics push编辑

通过使用本地旅程在 Kibana 中创建监控。默认情况下，运行 push 命令将使用 synthetics.config.ts 文件中的 project 设置字段，该字段是使用 init 命令设置的。但是，您可以使用 CLI 标志覆盖这些设置。

SYNTHETICS_API_KEY=<api-key> npx @elastic/synthetics push --url <kibana-url> --id <id|name>

push 命令包含交互式提示，以防止您意外删除或重复监控。当您

  • 您 push 一个以前包含一个或多个监控但不再包含以前运行的监控或有任何监控的项目。选择 yes 删除与正在推送的项目 ID 关联的监控。
  • 您 push 一个已经使用一个项目 ID 推送的项目，然后尝试使用不同的 ID push 它。选择 yes 创建项目中所有监控的副本。

您可以设置 DEBUG=synthetics 环境变量来捕获已删除的监控。

如果旅程包含除 @elastic/synthetics 之外的外部 NPM 包，那么在调用 push 命令时，这些包将与旅程代码一起捆绑。但是，在使用外部包时存在一些限制

  • 压缩后的捆绑旅程不应超过 1500 千字节。
  • 由于平台不一致，本机节点模块将无法按预期工作。
  • 不支持在旅程脚本中上传文件（通过 locator.setInputFiles）。
--auth <string>

用于 Kibana 身份验证 的 API 密钥。您也可以通过 SYNTHETICS_API_KEY 环境变量设置 API 密钥。

如果您正在推送到 私有位置，则必须使用在 8.4 或更高版本中生成的 API 密钥。

要创建 API 密钥，您必须以具有 写入者角色 中描述的特权的用户身份登录 Kibana。

--id <string>

与您的项目关联的唯一 ID。它将用于逻辑地对监控进行分组。

如果您使用 init 创建项目，这就是您指定的 <name-of-project>。

这也可以在配置文件中使用 project.id 设置。通过 CLI 定义的值优先。

--url <string>

要将监控上传到的部署的 Kibana URL。

这也可以在配置文件中使用 project.url 设置。通过 CLI 定义的值优先。

--space <string>

推送监控的目标 Kibana 空间 的标识符。空间有助于您组织推送的监控。如果未指定，则推送至“default”空间。

这也可以在配置文件中使用 project.space 设置。通过 CLI 定义的值优先。

--schedule <number>

监控应运行的间隔（以分钟为单位）。

这也可以在配置文件中使用 monitor.schedule 设置。通过 CLI 定义的值优先。

--locations Array<SyntheticsLocationsType>

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

要列出可用位置，请参阅 @elastic/synthetics locations。

这也可以在配置文件中使用 monitor.locations 在配置文件中 设置。通过 CLI 定义的值优先。

--private-locations Array<string>

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

要列出可用的私有位置，请参阅 @elastic/synthetics locations。

这也可以在配置文件中使用 monitor.privateLocations in the configuration file 设置。通过 CLI 定义的值将优先使用。

--yes

The push 命令包含交互式提示，以防止您意外删除或重复监视器。如果非交互式运行 CLI，则可以使用 --yes 选项覆盖这些提示。当 --yes 选项传递给 push

  • 如果您 push 一个以前包含一个或多个监视器但不再包含任何监视器的项目，则将删除与正在推送的项目 ID 关联的所有监视器。
  • 如果您 push 一个已经使用一个项目 ID 推送的项目，然后尝试使用不同的 ID push 它，它将创建项目中所有监视器的副本。

标记和过滤监视器edit

Synthetics 旅程可以使用一个或多个标签进行标记。使用标签在本地运行测试或将它们推送到 Kibana 时过滤旅程。

要向单个旅程添加标签，请将 tags 参数添加到 journey 函数或使用 monitor.use 方法。

import {journey, monitor} from "@elastic/synthetics";

journey({name: "example journey", tags: ["env:qa"] }, ({ page }) => {
  monitor.use({
    tags: ["env:qa"]
  })
  // Add steps here
});

对于轻量级监视器，请在 yaml 配置文件中使用 tags 字段。

name: example monitor
tags:
  - env:qa

要将标签应用于所有浏览器和轻量级监视器，请使用 monitor.tags 字段在 synthetics.config.ts 文件中进行配置。

« 监控私有网络上的资源 过滤监控 »