› › ›

使用 Synthetics 命令行界面

`@elastic/synthetics`

Synthetics 应用使用 @elastic/synthetics Node.js 库来运行合成浏览器测试并报告测试结果。该库还提供了一个命令行界面，可帮助您搭建脚手架、在本地开发/运行测试以及将测试推送到 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

以 headful 模式运行浏览器。

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

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

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

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

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

`@elastic/synthetics init`

编辑

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

这将创建一个模板 Node.js 项目，其中包括合成代理、必需的依赖项、合成配置文件以及示例浏览器和轻量级监控器文件。可以编辑这些文件，然后将其推送到 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 进行设置。通过 CLI 定义的值优先。

--fields <string>

将与每个监控器事件一起发送的键值对列表。fields 将作为 labels 附加到 Elasticsearch 文档，这些标签在 Kibana 中的单个监控器的概述选项卡的监控器详细信息面板中显示。

示例：--fields '{ "foo": bar", "team": "synthetics" }'

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

--yes

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

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

监控器的标签和过滤

编辑

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 文件中进行配置。

过滤监控器

编辑

运行 npx @elastic/synthetics push 命令时，您可以使用以下标志过滤推送到 Kibana 的监控器

--tags Array<string>: 推送与 glob 模式匹配的给定标签的监控器。
--match <string>: 推送名称或标签与 glob 模式匹配的监控器。
--pattern <string>: 正则表达式模式，用于匹配当前工作目录中的巡检文件。默认为 /*.journey.(ts|js)$/（对于浏览器监控器）和 /.(yml|yaml)$/（对于轻量级监控器）。

您可以结合这些技术，并通过使用多个配置文件将监控器推送到不同的 Kibana 集群/空间。

npx @elastic/synthetics push --config synthetics.qa.config.ts --tags env:qa
npx @elastic/synthetics push --config synthetics.prod.config.ts --tags env:prod

`@elastic/synthetics locations`

编辑

列出运行 Synthetics 监控器的所有可用位置。

npx @elastic/synthetics locations --url <kibana-host> --auth <api-key>

运行 npx @elastic/synthetics locations 命令不带任何标志即可列出 Elastic 管理的用于运行 Synthetics 监控器的所有可用全局位置。

要列出 Elastic 全球托管基础设施上的位置和私有位置，请包含

--url <string>: 用于获取所有可用公共和私有位置的部署的 Kibana URL。
--auth <string>: 用于 Kibana 身份验证的 API 密钥。

如果管理员已禁用您所分配角色的 Elastic 托管位置，并且您未包含 --url 和 --auth，则将列出 Elastic 管理的所有全局位置。但是，您将无法使用您的 API 密钥推送到这些位置，并且会看到错误：您无权使用 Elastic 托管的全局位置。有关更多详细信息，请参阅故障排除文档。

`@elastic/synthetics totp <secret>`

编辑

生成 Synthetics 中多因素身份验证 (MFA) 的基于时间的一次性密码 (TOTP)。

npx @elastic/synthetics totp <secret>
npx @elastic/synthetics totp <secret> --issuer <string> --label <string>

<secret>: 用于生成 TOTP 的编码密钥。
--issuer <string>: 与帐户关联的提供商或服务的名称。
--label <string>: 帐户的标识符。默认为 SyntheticsTOTP

« 监控私有网络上的资源配置 Synthetics 项目 »