使用 Synthetics 项目创建监视器

Elastic Stack Serverless（无服务器）

Synthetics 项目是配置合成监视器的最强大和最复杂的方式。Synthetics 项目允许您将基础设施定义为代码，更常被称为 IaaC 或 Git-ops。通过在 Synthetics 项目中创建和管理的监视器，您可以在文件系统上组织 YAML 配置和 JavaScript 或 TypeScript 定义的监视器，使用 Git 进行版本控制，并通过 CLI 工具进行部署，该工具通常在 CI/CD 平台上执行。

Diagram showing which pieces of software are used to configure monitors

这是您可以用来设置合成监视器的两种方法之一。

先决条件

对于**无服务器 Observability 项目**，您必须以具有 Editor（编辑者）访问权限的用户身份登录。

对于 **Elastic Stack 部署**，您必须以至少具有 synthetics 写入权限的用户身份登录到 Kibana，并且管理员必须按照设置角色中所述启用监视器管理。

使用 Synthetics 项目需要使用 Elastic Synthetics CLI 工具，该工具可以通过 npx @elastic/synthetics 命令调用。在开始之前，您需要

安装 Node.js
安装软件包
```
npm install -g @elastic/synthetics
```
确认您的系统已正确设置
```
npx @elastic/synthetics -h
```

在开始之前，您还应该决定要在哪里运行监视器。您可以在以下一个或两个位置的 Synthetics 项目中运行监视器

Elastic 的全球托管测试基础设施：使用 Elastic 的全球托管测试基础设施，您可以在多个位置创建和运行监视器，而无需管理自己的基础设施。Elastic 会为您处理软件更新和容量规划。
私有位置：私有位置允许您从自己的场所运行监视器。要使用私有位置，您必须先创建一个私有位置才能继续。有关分步说明，请参阅监视私有网络上的资源。

注意

如果您要为配置了流量过滤器的部署设置 Synthetics，则对 Elasticsearch 的连接受到限制，除非获得授权，否则结果将无法写回 Elasticsearch。有关更多详细信息，请参阅将 Synthetics 与流量过滤器结合使用。

创建 Synthetics 项目

首先创建您的第一个 Synthetics 项目。运行以下命令以在当前目录中创建一个名为 synthetic-project-test 的新 Synthetics 项目。

npx @elastic/synthetics init synthetic-project-test

然后，按照屏幕上的提示为您的 Synthetics 项目设置正确的默认变量。完成后，在您的终端中设置 SYNTHETICS_API_KEY 环境变量，该变量用于连接到您的 Observability 项目

Elastic Stack

要生成 API 密钥
1. 转到您的 Observability 项目中的 **Synthetics**。
2. 单击**设置**。
3. 切换到**项目 API 密钥**选项卡。
4. 单击**生成项目 API 密钥**。
  
  重要提示
  
  要生成项目 API 密钥，您必须以具有 Editor（编辑者）访问权限的用户身份登录。
  
  ×

要使用 API 密钥推送到 Elastic 的全球托管测试基础设施，生成 API 密钥时必须启用_启用 Elastic 托管位置_切换开关。如果禁用_启用 Elastic 托管位置_切换开关，则管理员已限制对 Elastic 全球托管测试基础设施的访问。

在您的终端中设置 SYNTHETICS_API_KEY 环境变量。您很可能希望永久设置它。这在 Powershell 和 Bash 中以不同的方式完成。

然后，查看 Synthetics 项目中的关键文件和目录

journeys 是您将添加 .ts 和 .js 文件以定义浏览器监视器的位置。当您创建一个新的 Synthetics 项目时，此目录将包含定义示例监视器的文件。
lightweight 是您将添加 .yaml 文件以定义轻量级监视器的位置。当您创建一个新的 Synthetics 项目时，此目录将包含一个定义示例监视器的文件。
synthetics.config.ts 包含您的 Synthetics 项目的设置。当您创建一个新的 Synthetics 项目时，它将包含一些基本的配置选项，您可以稍后自定义这些选项。

注意

示例 Synthetics 项目中的 synthetics.config.ts 使用 Elastic 全球托管测试基础设施上的一个位置。管理员可以限制对 Elastic 全球托管测试基础设施的访问。当您尝试 push 示例监视器时，如果您看到一个错误，指出您没有权限使用 Elastic 托管的全球位置，请参阅故障排除指南以获取指导。
package.json 包含您的 Synthetics 项目的 NPM 设置。在 NPM 文档中了解更多信息。
.github 包含用于 GitHub Actions 的示例工作流程文件。

Serverless（无服务器）

要生成 API 密钥
1. 转到您的 Observability 项目中的 **Synthetics**。
2. 单击**设置**。
3. 切换到**项目 API 密钥**选项卡。
4. 单击**生成项目 API 密钥**。
  
  重要提示
  
  要生成项目 API 密钥，您必须以具有 Editor（编辑者）访问权限的用户身份登录。
  
  ×

在您的终端中设置 SYNTHETICS_API_KEY 环境变量。您很可能希望永久设置它。这在 Powershell 和 Bash 中以不同的方式完成。

然后，查看 Synthetics 项目中的关键文件和目录

journeys 是您将添加 .ts 和 .js 文件以定义浏览器监视器的位置。当您创建一个新的 Synthetics 项目时，此目录将包含定义示例监视器的文件。
lightweight 是您将添加 .yaml 文件以定义轻量级监视器的位置。当您创建一个新的 Synthetics 项目时，此目录将包含一个定义示例监视器的文件。
synthetics.config.ts 包含您的 Synthetics 项目的设置。当您创建一个新的 Synthetics 项目时，它将包含一些基本的配置选项，您可以稍后自定义这些选项。

注意

示例 Synthetics 项目中的 synthetics.config.ts 使用 Elastic 全球托管测试基础设施上的一个位置。管理员可以限制对 Elastic 全球托管测试基础设施的访问。当您尝试 push 示例监视器时，如果您看到一个错误，指出您没有权限使用 Elastic 托管的全球位置，请参阅故障排除指南以获取指导。
package.json 包含您的 Synthetics 项目的 NPM 设置。在 NPM 文档中了解更多信息。
.github 包含用于 GitHub Actions 的示例工作流程文件。

检查示例监视器

在 lightweight 目录中，您将找到示例轻量级监视器。这是一个定义轻量级监视器的 YAML 文件示例

		# lightweight.yml
heartbeat.monitors:
- type: http
  name: Todos Lightweight
  id: todos-lightweight
  urls: "https://elastic.github.io/synthetics-demo/"
  schedule: '@every 1m'

	

有关轻量级监视器配置选项的更多详细信息，请参阅配置轻量级监视器。

在 journeys 目录中，您将找到示例浏览器监视器。这是一个定义浏览器监视器的 TypeScript 文件示例

		// example.journey.ts
import { journey, step, monitor, expect } from '@elastic/synthetics';
journey('My Example Journey', ({ page, params }) => {
  // Only relevant for the push command to create
  // monitors in Kibana or your serverless Observability project
  monitor.use({
    id: 'example-monitor',
    schedule: 10,
  });
  step('launch application', async () => {
    await page.goto(params.url);
  });
  step('assert title', async () => {
    const header = await page.locator('h1');
    expect(await header.textContent()).toBe('todos');
  });
});

	

有关编写 journeys 和配置浏览器监视器的更多详细信息，请参阅编写浏览器监视器脚本。

测试并连接到您的 Observability 项目或 Elastic Stack 部署

Elastic Stack

在项目目录中，您可以使用 npx @elastic/synthetics 命令执行两项操作

在本地测试基于浏览器的监视器。要运行在 .ts 和 .js 文件中定义的所有 journeys
```
npx @elastic/synthetics journeys
```
将所有监视器配置推送到 Elastic 部署。从您的项目中运行以下命令
```
npx @elastic/synthetics push --auth $SYNTHETICS_API_KEY --url <kibana-url>
```

每个 journey 或轻量级监视器将在 Synthetics 应用程序中显示一个监视器，并且您将从本地环境管理所有监视器。有关使用 push 命令的更多详细信息，请参阅 @elastic/synthetics push。

注意

如果您添加了私有位置，您可以 push 到该私有位置。

要列出可用的私有位置，请运行 elastic-synthetics locations 命令，并提供 Kibana URL，以便从该部署中获取可用的位置。

Serverless（无服务器）

在 Synthetics 项目目录中，你可以使用 npx @elastic/synthetics 命令执行两项操作

在本地测试基于浏览器的监视器。要运行在 .ts 和 .js 文件中定义的所有 journeys
```
npx @elastic/synthetics journeys
```
将所有监控配置推送到 Observability 项目。从你的 Synthetics 项目目录中运行以下命令
```
npx @elastic/synthetics push --auth $SYNTHETICS_API_KEY --url <observability-project-url>
```

每个 Journey 或轻量级监控器都将在 Synthetics UI 中显示一个监控器，并且你将从本地环境管理所有监控器。有关使用 push 命令的更多详细信息，请参阅 @elastic/synthetics push。

注意

如果您添加了私有位置，您可以 push 到该私有位置。

要列出可用的私有位置，请运行 elastic-synthetics locations 命令，并提供 Observability 项目的 URL，以便从中获取可用的位置。

在 Synthetics UI 中查看

然后，转到无服务器 Observability 项目或 Kibana 中的 Synthetics。你应该看到你新推送的监控器正在运行。你也可以转到 Management 选项卡以查看监控器的配置设置。

注意

创建或更新监控器时，第一次运行可能不会立即发生，但第一次运行发生的时间将少于监控器配置的频率。例如，如果创建了一个监控器并将其配置为每 10 分钟运行一次，则第一次运行将在创建后的 10 分钟内发生。第一次运行后，监控器将根据配置的频率开始定期运行。如果你想更快地查看结果，可以运行手动测试。

后续步骤

了解更多关于