使用 Synthetics 项目创建监控

Elastic Stack Serverless

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

Diagram showing which pieces of software are used to configure monitors

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

先决条件

对于无服务器可观测性项目，您必须以具有Editor 访问权限的用户身份登录。

对于Elastic Stack 部署，您必须以至少具有synthetics write permissions 的用户身份登录 Kibana，并且 Monitor Management 必须由管理员启用，如Setup role 中所述。

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

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

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

Elastic 的全球托管测试基础架构：使用 Elastic 的全球托管测试基础架构，您可以在多个位置创建和运行监控，而无需管理自己的基础架构。Elastic 会为您处理软件更新和容量规划。
私有位置：私有位置允许您从自己的 premises 运行监控。要使用私有位置，您必须先创建私有位置。有关分步说明，请参阅监控私有网络中的资源。

注意

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

创建 Synthetics 项目

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

npx @elastic/synthetics init synthetic-project-test

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

Elastic Stack

生成 API 密钥
1. 在您的可观测性项目中，转到 **Synthetics**。
2. 点击 **Settings**。
3. 切换到 **Project API Keys** 选项卡。
4. 点击 **Generate Project API key**。
  
  重要提示
  
  要生成 Project API 密钥，您必须以具有Editor 访问权限的用户身份登录。
  
  ×

要使用 API 密钥推送到 Elastic 的全球托管测试基础架构，生成 API 密钥时必须开启 Elastic managed locations enabled (Elastic 托管位置已启用) 开关。如果 Elastic managed locations enabled (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 一起使用的示例工作流文件。

无服务器

生成 API 密钥
1. 在您的可观测性项目中，转到 **Synthetics**。
2. 点击 **Settings**。
3. 切换到 **Project API Keys** 选项卡。
4. 点击 **Generate Project API key**。
  
  重要提示
  
  要生成 Project 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');
  });
});

	

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

测试并连接到您的可观测性项目或 Elastic Stack 部署

Elastic Stack

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

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

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

注意

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

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

无服务器

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

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

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

注意

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

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

在 Synthetics UI 中查看

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

注意

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

后续步骤

了解更多关于