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 的综合监控脚本中你不需要引入任何依赖以下对象已经预置于执行上下文可直接使用对象说明pagePlaywright 的Page对象用于与浏览器交互点击、填表、截图、跳转browserType当前执行上下文的浏览器类型Chromium、Firefox、WebkitscreenSizeType当前执行上下文的屏幕尺寸类型Mobile、Tablet、Desktopscreenshots预声明的截图集合对象赋值即可保存截图monitorSecrets该监控被授权访问的监控密钥Monitor Secretsaxios基于 Promise 的 HTTP 客户端可在脚本中发起 HTTP 请求cryptoNode.js 内置加密模块哈希、HMAC、加解密、签名等http/httpsNode.js 内置 HTTP/HTTPS 客户端与服务器模块console.log控制台日志会出现在监控的日志Logs区块中oneuptime.captureMetric上报自定义指标的函数见下文自定义指标一个最小可运行的综合监控脚本如下// 打开目标页面 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、FirefoxWebkit在枚举中被注释尚未开放屏幕尺寸Mobile、Tablet、Desktop。在探针执行器 SyntheticMonitor.execute 中执行逻辑按「先遍历浏览器类型、再遍历屏幕尺寸」的双重循环展开每次组合生成一条独立的监控结果。不同屏幕尺寸对应不同的视口viewport在 getViewportHeightAndWidth 中硬编码为屏幕尺寸视口宽 × 高Desktop1920 × 1080Mobile360 × 640Tablet1024 × 768因此你完全可以在脚本里根据browserType/screenSizeType做分支例如为移动端执行不同的断言路径。Playwright 页面交互OneUptime 使用 Playwright 驱动浏览器page就是 Playwright 的Page对象支持完整页面 APIgoto、fill、click、waitForSelector、screenshot、context等。你可以用它模拟真实用户行为例如登录流程await page.goto(https://app.example.com/login); await page.fill(#email, userexample.com); await page.fill(#password, password); await page.click(button[typesubmit]); 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, userexample.com); await page.fill(#password, wrong); await page.click(button[typesubmit]); // 如果下面的断言抛错上面的 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);参数说明参数类型必填说明namestring是指标名称例如dashboard.load.time存储时自动加上custom.monitor.前缀valuenumber是指标数值attributesobject否键值对形式的额外上下文标签实战示例——测量仪表盘加载耗时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字段会被提取并序列化为普通 JSONtoJsonSafeResultNaN/Infinity变为null、undefined属性和函数被丢弃、Date转为 ISO 字符串只有真正无法序列化的值如循环引用、BigInt才会导致结果被丢弃。因此请确保返回的数据可 JSON 序列化。最佳实践与注意事项综合以上文档与源码编写稳健的综合监控脚本时建议遵循始终使用侧信道screenshots保存关键步骤截图而不是依赖return中的截图——失败现场对排查问题至关重要把敏感信息放进 Monitor Secrets通过monitorSecrets占位符注入绝不硬编码进脚本脚本控制在 2 分钟超时之内避免长轮询或死循环导致脚本被强制终止超时后探针会记录失败但可以通过截图还原当时的页面状态利用browserType/screenSizeType做平台差异化断言因为同一脚本会在多种浏览器与视口组合下执行用console.log记录关键分支日志会出现在监控的 Logs 区块方便定位执行路径为关键用户旅程上报自定义指标如登录耗时、页面加载耗时并在 Metric Explorer 中配置图表与告警返回数据保持 JSON 安全return { data: ... }中的内容应可序列化自托管用户记得升级探针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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考