企业官网建设流程全解析

OneUptime 综合监控（Synthetic Monitor）实战指南：用 Playwright 脚本模拟真实用户、采集自定义指标与失败证据

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

综合监控（Synthetic Monitoring）是 OneUptime 提供的主动式应用监控能力：通过在探针（Probe）上运行用户编写的 JavaScript 脚本，用真实的 Playwright 浏览器自动化模拟用户点击、填表、跳转等交互，从而在全球不同位置持续验证应用的可达性与性能。读完本文，你将掌握 OneUptime 综合监控脚本的完整编写规范——脚本上下文对象、截图证据采集、监控密钥注入、自定义指标上报，以及探针侧的底层执行与超时、重试、并发等运行机制。

本文以 综合监控官方文档 为骨架，并深入 Probe 包的源码（SyntheticMonitor 执行器、运行时限制配置、探针配置）与对应测试，帮你既会写脚本，也理解它在后台是如何被执行的。

什么是综合监控

综合监控（Synthetic Monitor）与被动式监控（等待真实用户出错）不同，它属于主动探测：监控脚本会像真实用户一样访问你的应用，从多个地理位置持续发起模拟交互，从而在用户发现问题之前先发现可用性与性能问题。

OneUptime 综合监控的核心思路是用代码定义一次用户旅程：

• 脚本运行在探针（Probe）上，由探针驱动真实浏览器执行；
• 一个监控实例可以按浏览器类型 × 屏幕尺寸组合循环执行（见下文"浏览器与屏幕尺寸"），从而覆盖不同终端形态；
• 脚本中可以断言页面状态、采集截图、上报自定义指标、返回结构化数据，供仪表盘展示与告警使用。

脚本上下文：开箱即用的对象

在 OneUptime 的综合监控脚本中，你不需要引入任何依赖，以下对象已经预置于执行上下文，可直接使用：

一个最小可运行的综合监控脚本如下：

// 打开目标页面 await page.goto("https://playwright.dev/"); // 查看当前浏览器与屏幕尺寸上下文 console.log(browserType); // Chromium / Firefox / Webkit console.log(screenSizeType); // Mobile / Tablet / Desktop // page 属于当前这个具体的浏览器上下文， // 可通过 page.context() 访问浏览器上下文（例如创建新页面或管理弹窗）。 // 保存截图：截图会被持久化，即使脚本后续抛错也依然保留 screenshots["nom-capture"] = await page.screenshot(); // 返回数据：使用 return 语句，并把数据放在 data 字段中 return { data: "Hello World", };

脚本本质上是标准 JavaScript，因此你可以使用全部 JavaScript 语言特性来编排这些对象。

浏览器类型与屏幕尺寸

脚本中的browserType与screenSizeType并非固定值，而是反映当前这次执行的上下文。从 BrowserType 定义 与 ScreenSizeType 定义 可以看到当前支持的类型：

• 浏览器：Chromium、Firefox（Webkit在枚举中被注释，尚未开放）；
• 屏幕尺寸：Mobile、Tablet、Desktop。

在探针执行器 SyntheticMonitor.execute 中，执行逻辑按「先遍历浏览器类型、再遍历屏幕尺寸」的双重循环展开，每次组合生成一条独立的监控结果。不同屏幕尺寸对应不同的视口（viewport），在 getViewportHeightAndWidth 中硬编码为：

因此你完全可以在脚本里根据browserType/screenSizeType做分支，例如为移动端执行不同的断言路径。

Playwright 页面交互

OneUptime 使用 Playwright 驱动浏览器，page就是 Playwright 的Page对象，支持完整页面 API：goto、fill、click、waitForSelector、screenshot、context等。你可以用它模拟真实用户行为，例如登录流程：

await page.goto("https://app.example.com/login"); await page.fill("#email", "user@example.com"); await page.fill("#password", "password"); await page.click("button[type=submit]"); await page.waitForSelector(".dashboard", { timeout: 5000 });

截图证据：失败也能看到页面现场

综合监控最有价值的调试能力之一是截图证据。脚本上下文中预声明了一个screenshots对象，你可以在任意时刻把截图赋给它：

screenshots["nom-capture"] = await page.screenshot();

关键特性在于：这些截图即使在脚本抛错后依然被保留——包括断言失败（如waitForSelector超时）、脚本超时或任何意外错误。因此你可以看到执行失败那一刻页面的真实样子。截图会展示在 OneUptime 仪表盘中该次监控执行的详情里。

典型用法——在登录失败场景中保留关键页面证据：

await page.goto("https://app.example.com/login"); screenshots["page-connexion"] = await page.screenshot(); await page.fill("#email", "user@example.com"); await page.fill("#password", "wrong"); await page.click("button[type=submit]"); // 如果下面的断言抛错，上面的 `page-connexion` 截图依然被保留 await page.waitForSelector(".dashboard", { timeout: 5000 }); screenshots["tableau-de-bord"] = await page.screenshot(); return { data: "Connexion réussie", };

遗留模式：通过 return 返回截图

为兼容旧脚本，OneUptime 也支持在return值中携带screenshots字段。但注意：通过return返回的截图只在脚本正常结束时才被保留，一旦脚本抛错就会丢失。因此官方建议优先使用侧信道（side-channel）的screenshots对象来保存失败现场，return方式仅用于确需返回截图数据的兼容场景：

// 遗留模式 —— 截图仅在 return 成功时保留 const screenshots = {}; screenshots["nom-capture"] = await page.screenshot(); return { data: "Hello World", screenshots: screenshots, };

从 SyntheticMonitorResponse 类型 可以看到，截图最终以 Base64 编码的形式随监控结果返回，并带有browserType与screenSizeType标识，便于在结果中区分不同组合的执行。

使用监控密钥（Monitor Secrets）

如果你的脚本需要访问 API Key、令牌等敏感信息，不应该把密钥硬编码进脚本，而应使用 OneUptime 的监控密钥（Monitor Secrets）功能。

添加密钥

在 OneUptime 仪表盘中操作：Moniteurs（监控）→ 参数设置（Settings）→ Secrets（密钥）→ 创建监控密钥（Create Monitor Secret）。

创建时可以选择哪些监控（Monitor）有权访问该密钥。例如添加一个名为ApiKey的密钥，并勾选允许访问它的监控实例。只有被授权的监控脚本才能解析到该密钥。

重要安全说明：密钥是加密存储的，保存后无法再次查看或更新。如果遗失密钥，只能删除并重新创建一个新密钥，再重新分配给相关监控。

关于密钥在仪表盘与脚本间的完整使用流程，还可以参考 监控密钥文档（英文版见 monitor-secrets.en）。

在脚本中引用密钥

脚本通过monitorSecrets对象引用密钥。引用语法是模板占位符，并且类型不同写法不同：

// 字符串类型的密钥必须加引号 let secretString = '{{monitorSecrets.StringSecret}}'; // number / boolean 类型的密钥直接使用，不加引号 let secretNombre = {{monitorSecrets.NumberSecret}}; let secretBooleen = {{monitorSecrets.BooleanSecret}}; // 可以用 console.log 验证密钥是否正确注入 console.log(secretString);

自定义指标（Custom Metrics）

综合监控脚本可以上报自定义指标，用于衡量真实用户旅程中的关键性能数据（如登录耗时、页面渲染耗时）。API 签名如下：

oneuptime.captureMetric(name, value, attributes);

参数说明：

实战示例——测量仪表盘加载耗时：

await page.goto("https://app.example.com"); const startTime = Date.now(); await page.waitForSelector("#dashboard-loaded"); const loadTime = Date.now() - startTime; // 上报自定义指标：最终名称为 custom.monitor.dashboard.load.time oneuptime.captureMetric("dashboard.load.time", loadTime, { page: "dashboard", }); screenshots["tableau-de-bord"] = await page.screenshot(); return { data: { loadTime }, };

指标上报后，会出现在 OneUptime 的Metric Explorer（指标浏览器）中，名称形如custom.monitor.dashboard.load.time。你可以：

• 把这些指标添加到仪表盘图表中；
• 为它们配置告警规则；
• 按监控（monitor）、探针（probe）、浏览器类型、屏幕尺寸或任何自定义属性进行过滤。

自定义指标在探针端会随执行结果一并收集：在 SyntheticMonitor.executeByBrowserAndScreenSize 中，worker 进程返回的capturedMetrics数组会被写入监控结果（scriptResult.capturedMetrics），随后持久化到 OneUptime。

指标限额

为保证系统稳定性，自定义指标有以下限制：

• 单次脚本执行最多上报100 条指标；
• 指标名称最长200 个字符；
• 指标值必须是数值类型。

探针侧执行机制：脚本在后台如何运行

理解脚本在探针上的执行方式，有助于你写出更稳定、可预期的监控脚本。以下机制均可在 SyntheticMonitor.ts 源码中得到印证。

独立的 worker 进程与沙箱

综合监控脚本并非直接运行在探针主进程内。探针通过 ProcessRunner 启动独立的worker 进程（入口为 SyntheticMonitorWorker），脚本在 worker 内驱动浏览器执行。这样做的直接好处是：

• 脚本崩溃、浏览器异常不会拖垮探针主进程；
• 探针可以限制 worker 的并发数、内存（进程树 RSS）与磁盘占用，见 探针配置 中的相关环境变量：
  • PROBE_SYNTHETIC_MONITOR_MAX_CONCURRENCY：综合监控最大并发数；
  • PROBE_SYNTHETIC_MONITOR_MAX_PROCESS_TREE_RSS_BYTES：整个进程树的最大常驻内存；
  • PROBE_SYNTHETIC_MONITOR_MAX_DISK_BYTES：单次执行的最大磁盘占用（防止截图等撑爆磁盘）；
  • PROBE_SYNTHETIC_MONITOR_CHROMIUM_SANDBOX_ENABLED：是否启用 Chromium 的 OS 沙箱（容器环境下需要配合 seccomp profile，探针启动时会检测该开关，见 Index.ts）。

浏览器与执行超时

每个（浏览器 × 屏幕尺寸）组合都会启动一次独立执行。探针在构造 worker 配置时写入timeoutInMs（来自PROBE_SYNTHETIC_MONITOR_SCRIPT_TIMEOUT_IN_MS），并从 运行时限制 中读取启动宽限时间（SYNTHETIC_MONITOR_WORKER_STARTUP_ALLOWANCE_IN_MS，默认 120 秒）。

• 面向用户的脚本超时默认 2 分钟：脚本运行超过该时长即被终止（文档明确说明：超过 2 分钟脚本会被强制停止）；
• 面向探针运营者的总超时 = 脚本超时 + 启动宽限时间，用于覆盖浏览器启动与 worker 就绪的耗时；
• 超时上限有约束：Node.js 定时器无法安全表示超过2^31 - 1毫秒的延迟，因此最大脚本超时被限制为MAX_NODE_TIMER_DELAY_IN_MS - SYNTHETIC_MONITOR_WORKER_STARTUP_ALLOWANCE_IN_MS（见 Limits.ts），相关约束有专门测试覆盖（ConfigSyntheticMonitorTimeout.test.ts）。

重试机制

脚本失败时的重试策略在 executeWithRetry 中实现，规则值得注意：

• 脚本错误：按你在监控上配置的"出错重试次数"（Retry Count On Error）重试，两次重试间默认等待 1 秒；
• 运行时故障：如果是探针自身运行时故障（浏览器启动失败、沙箱未就绪等，即脚本根本没跑起来），即使租户配置的重试次数为 0，探针也会至少额外重试 1 次（间隔 2 秒），避免把探针侧瞬时问题误报成租户脚本错误；
• 每次尝试都会记录到retryAttempts历史中（仅当多于一次尝试时才会填充，以减少日志负载），最终结果包含totalAttempts与单次执行耗时executionTimeInMS。

代理与浏览器二进制

若探针配置了 HTTP/HTTPS 代理，综合监控浏览器会通过代理访问外网（getBrowserProxy）：优先使用 HTTPS 代理，回退到 HTTP 代理，并支持从代理 URL 中解析用户名/密码进行认证；同时内置的控制器地址与NO_PROXY列表会被加入代理绕过名单。Chromium 与 Firefox 的可执行文件路径由探针在 Playwright 浏览器缓存目录（默认~/.cache/ms-playwright）中按目录名匹配自动定位（见getChromeExecutablePath/getFirefoxExecutablePath）。

返回值与 JSON 序列化

脚本return的data字段会被提取并序列化为普通 JSON（toJsonSafeResult）：NaN/Infinity变为null、undefined属性和函数被丢弃、Date转为 ISO 字符串；只有真正无法序列化的值（如循环引用、BigInt）才会导致结果被丢弃。因此请确保返回的数据可 JSON 序列化。

最佳实践与注意事项

综合以上文档与源码，编写稳健的综合监控脚本时建议遵循：

1. 始终使用侧信道screenshots保存关键步骤截图，而不是依赖return中的截图——失败现场对排查问题至关重要；
2. 把敏感信息放进 Monitor Secrets，通过monitorSecrets占位符注入，绝不硬编码进脚本；
3. 脚本控制在 2 分钟超时之内，避免长轮询或死循环导致脚本被强制终止；超时后探针会记录失败，但可以通过截图还原当时的页面状态；
4. 利用browserType/screenSizeType做平台差异化断言，因为同一脚本会在多种浏览器与视口组合下执行；
5. 用console.log记录关键分支，日志会出现在监控的 Logs 区块，方便定位执行路径；
6. 为关键用户旅程上报自定义指标（如登录耗时、页面加载耗时），并在 Metric Explorer 中配置图表与告警；
7. 返回数据保持 JSON 安全，return { data: ... }中的内容应可序列化；
8. 自托管用户记得升级探针：OneUptime 云端始终提供最新版 Playwright 与浏览器；自托管时请及时更新探针镜像，以获得最新的浏览器版本与运行时修复。

关于综合监控脚本的更底层行为，还可以阅读 Probe 包中的系列测试作为补充：如 SyntheticMonitor.test.ts、SyntheticMonitorWorkerLifecycle.test.ts 与 SyntheticMonitorWorkerIntegration.test.ts，它们验证了 worker 生命周期、执行结果契约与失败传播等关键行为。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime