› › ›

使用 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 文件的 RegExp 模式。默认为 /*.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 内联脚本化的 journeys 并通过 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 命令的帮助。

仅当您在本地运行合成测试或将其推送到 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`

编辑

通过使用您的本地 journeys 在 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 环境变量以捕获已删除的监控器。

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

压缩后的捆绑 journey 不应超过 1500 KB。
由于平台不一致，本地节点模块将无法按预期工作。
不支持在 journey 脚本中上传文件（通过 locator.setInputFiles）。

--auth <string>

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

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

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

--id <string>

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

如果您使用init 来创建项目，则这是您指定的 <项目名称>。

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

--url <string>

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

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

--space <string>

推送的监控器的目标Kibana 空间的标识符。空间可帮助您组织推送的监控器。如果未指定，则推送到“默认”空间。

这也可以使用 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 push 一个已推送的项目，然后尝试使用不同的 ID push 它，则会在项目中创建所有监控器的副本。

标记和过滤监控器

编辑

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>: 用于匹配当前工作目录中旅程文件的 RegExp 模式。对于浏览器监控器，默认为 /*.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 项目 »