从 Uptime 到 Synthetics 在 Elastic 中的迁移手册

作者：来自 Elastic Carles Salvador

使用这份完整指南，你可以轻松地将现有的 Uptime TCP、ICMP 和 HTTP 监控迁移到 Elastic Synthetics，并利用 Private Locations 和 Synthetics Projects 实现高效、面向未来的监控。

你有没有看到 Uptime 已被弃用的提示，并想知道如何轻松迁移到 Synthetics？那你来对地方了。从 8.15.0 版本开始，Uptime 检查已被弃用，推荐使用 Synthetics 监控。

许多用户可能已经有大量的 TCP、ICMP 和 HTTP 监控，需要迁移到 Synthetics。在本指南中，我们会解释如何轻松完成迁移，同时确保迁移方案具备前瞻性，并能够扩展到更高级的检查，比如 Browser 监控。

首先，我们要考虑要迁移的监控数量；如果数量很少，最简单的方法就是通过 Synthetics UI 手动操作。不过在本指南中，我们假设需要迁移几十甚至上百个监控，手动在 Synthetics UI 里完成是不现实的。

Private Location

传统上，Uptime 监控需要在你的基础设施中部署 Heartbeat，这样才能间接监控私有网络中的端点或主机。如果你仍然有这个需求，就需要配置 Private Location ，或者允许 Elastic 的全球托管基础设施访问你的私有端点（仅限 ECH & Serverless）。

在本指南中，我们将使用 Private Locations ，这样你可以同时监控内部和外部资源。更多详情请参考：Monitor resources on private networks。

第一步：设置 Fleet Server 和 Elastic Agent

Private Locations 本质上就是注册到 Fleet 并通过 Agent 策略管理的 Elastic Agent。

如果你还没有 Fleet Server ，需要先设置一个 Fleet Server。

👉 如果你使用的是 ECH，则无需这一步，因为它默认自带。
接下来，你需要创建一个 Agent Policy：
1. 打开 Observability → Monitors (Synthetics)
2. 点击右上角 Settings
3. 进入 Private Location
4. 点击 + Create Location

填写字段并为这个 Private Location 创建一个新策略。重要的是要知道 Private Location 应该基于运行在单个 Elastic Agent 上的代理策略进行设置。

步骤 2：部署 Elastic Agent

现在我们需要部署负责运行所有监视器的 Elastic Agent。我们可以使用之前用于 Heartbeat 的同一台主机。只有一个要求：我们必须能够运行 Docker 容器，因为要利用 Synthetics 的所有功能，我们必须使用 elastic-agent-complete Docker Image。

进入 Fleet → Enrollment tokens ，并记下与你刚刚为 Private Location 创建的策略相关的 enrollment token。现在进入 Settings，并记下默认的 Fleet server host URL。
在主机上运行以下命令。有关使用 Docker 运行 Elastic Agent 的更多信息，请参阅 Run Elastic Agent in a container。

ini 复制代码

`

1.  docker run \
2.    --env FLEET_ENROLL=1 \
3.    --env FLEET_URL={fleet_server_host_url} \
4.    --env FLEET_ENROLLMENT_TOKEN={enrollment_token} \
5.    --cap-add=NET_RAW \
6.    --cap-add=SETUID \
7.    --rm docker.elastic.co/elastic-agent/elastic-agent-complete:9.1.2

`AI写代码

Synthetic Project

此时，我们已经有了运行 Synthetic 监视器的位置。现在我们需要将 Uptime 监视器加载为 Synthetics。

正如我们之前提到的，有两种方法可以做到这一点：要么通过 Synthetics UI 手动操作，要么通过 Synthetics Project 。在我们的情况下，由于需要迁移的监视器太多，不想手动操作，所以我们将使用 Synthetics Projects。

Synthetics Project 的好处在于它对 heartbeat.yml 中定义的监视器有一定的向后兼容性，我们将利用这一点。

什么是 Synthetics project？

Synthetics project 是在 Elastic 中管理 synthetic 监视器最强大和灵活的方式，它基于 Infrastructure as Code 原则，并且兼容 Git-Ops 流程。你不是通过界面配置监视器，而是将它们定义为代码：轻量级监视器使用 .yml 文件，浏览器类型监视器（journeys）使用 JavaScript 或 TypeScript 脚本。

这种方法允许你将监视器结构化地放在一个代码库中，用 Git 进行版本管理、验证，并通过 CI/CD 流程自动部署，从而提供可追溯性、代码审查和一致的部署。

Step 3: 初始化你的 Synthetics project

你不再需要连接到部署 Elastic Agent 的主机，因为剩下的步骤只要你能连接到 Kibana，就可以在本地完成！

由于 Synthetics Projects 基于 Node.js，请确保你已经安装了它。

1）安装包：

bash 复制代码

`npm install -g @elastic/synthetics` AI写代码

2）确认系统已正确设置：

bash 复制代码

`npx @elastic/synthetics -h` AI写代码

3）首先创建你的第一个 Synthetics project。在当前目录下运行以下命令来创建一个名为 synthetic-project-test 的新 Synthetics project：

kotlin 复制代码

`npx @elastic/synthetics init synthetic-project-test` AI写代码

4）按照提示配置 Synthetics project 的默认变量。请务必至少选择你的 Private Location 。完成后，在终端中设置 SYNTHETICS_API_KEY 环境变量，以便项目可以与 Kibana 进行认证。

生成 API key 的方法：

进入 Synthetics Kibana
点击 Settings
切换到 Project API Keys 标签
点击 Generate Project API key

更多步骤详情请参考：Create monitors with a Synthetics project

Step 4：添加你的 heartbeat.yml 文件

项目初始化后，进入它创建的文件夹，查看项目结构：

journeys：用于添加定义浏览器监控的 .ts 和 .js 文件，目前包含定义示例监控的文件。
lightweight：用于添加定义轻量级监控的 heartbeat.yml 文件，目前包含定义示例监控的文件。

因此，我们只需将 heartbeat.yml 文件复制到这个 lightweight 文件夹。在复制 heartbeat.yml 之前，请注意我们并不需要全部内容，只关心 heartbeat.monitors 部分。

建议将文件拆分为逻辑组。与其维护一个大的 YAML 文件，不如创建多个较小的 YAML 文件，每个文件代表单个检查或一组相关检查。这样可以简化管理，并提高与 GitOps 工作流的兼容性。

每个 YAML 文件应如下所示：

css 复制代码

`

1.  carles@synthetics-migration:synthetic-project-test/lightweight# cat heartbeat.yml

3.  heartbeat.monitors:
4.  - type: icmp
5.    schedule: '@every 10s'
6.    hosts: ["localhost"]
7.    id: my-icmp-service-synth
8.    name: My ICMP Service - Synthetic
9.  - type: tcp
10.    schedule: '@every 10s'
11.    hosts: ["myremotehost:8123"]
12.    mode: any
13.    id: my-tcp-service-synth
14.    name: My TCP Service Synthetic
15.  - type: http
16.    schedule: '@every 10s'
17.    urls: ["http://elastic.co"]
18.    id: my-http-service-synth
19.    name: My HTTP Service Synthetic

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

我们刚刚做的是将不同的 ICMP、TCP 和 HTTP 检查定义为代码。

现在我们需要让 Synthetics project 根据 YAML 文件中定义的内容在 Kibana 中创建监控：

bash 复制代码

`npx @elastic/synthetics push --auth $SYNTHETICS_API_KEY --url <kibana-url>` AI写代码

不幸的是，我们不支持 heartbeat schema 与 lightweight schema 的一对一映射，因此在执行此命令时可能会遇到一些错误。一个例子是 schedule 的定义。Heartbeat 支持使用 crontab 表达式，但 Project 要求使用 @every 语法。

如果未发现语法错误，命令输出将显示监控已成功在 Kibana 中创建！

然后，进入 Kibana 的 Synthetics，你应该能看到新推送的监控正在运行。你也可以进入 Management 标签查看监控的配置设置。

原文：www.elastic.co/observabili...