使用 Playwright 编写 OneUptime 合成监控脚本：从模拟用户交互到自定义指标采集

使用 Playwright 编写 OneUptime 合成监控脚本从模拟用户交互到自定义指标采集【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime合成监控Synthetic Monitoring是一种通过模拟真实用户交互来主动探测应用可用性与性能的监控方式。本指南以 OneUptime 的合成监控Synthetic Monitor为核心讲解如何使用内置的 Playwright 兼容page对象编写浏览器交互脚本、通过screenshots侧通道保留失败现场证据、利用monitorSecrets安全注入敏感信息并通过oneuptime.captureMetric()输出自定义指标用于 Metric Explorer 可视化与告警。读完本文你将能够编写一份可运行、可调试、可复用的合成监控脚本。合成监控是什么OneUptime 的合成监控通过模拟用户交互点击按钮、填写表单、页面跳转、截图取证等来主动验证应用在全球不同地理位置的可用性与性能而不是被动等待真实用户报告故障。你只需在监控脚本中描述一个用户会怎么做探针Probe就会代表你在目标站点上重复执行这些行为。与简单的 HTTP 探测不同合成监控运行在一个真实的浏览器上下文中因此可以覆盖以下场景登录流程、购物车结算、多步表单等复杂交互链路的可用性前端页面渲染速度、关键元素出现时间等性能指标从多个地理位置、多种浏览器内核与屏幕尺寸组合下的一致性验证。从源码结构看OneUptime 的合成监控由探针侧的 SyntheticRuntime 运行环境 完整支撑它包含 SyntheticMonitorWorker.ts浏览器 Worker 入口、WorkerController.tsRPC 能力控制器、PlaywrightCapabilityBroker.tsPlaywright 能力代理与 WorkerBootstrap.ts沙箱引导代码等模块负责将用户脚本安全地映射到真实浏览器操作上。快速开始一个最小可用脚本在 OneUptime Dashboard 中创建合成监控后你会获得一个脚本编辑入口。以下示例完整展示了脚本上下文script context中可用的对象以及最基本的打开页面 → 截图 → 返回数据流程// Objects available in the context of the script are: // - axios: Axios module to make HTTP requests // - page: OneUptimes secure Playwright-compatible page facade // - browserType: Browser type in the current run context - Chromium or Firefox // - screenSizeType: Screen size type in the current run context - Mobile, Tablet, Desktop // You can use these objects to interact with the browser and make HTTP requests. await page.goto(https://playwright.dev/); // The commonly used Page, Locator, Frame, and BrowserContext APIs are supported. // Here are some of the variables that you can use in the context of the monitored object: console.log(browserType); // This will list the browser type in the current run context - Chromium or Firefox console.log(screenSizeType); // This will list the screen size type in the current run context - Mobile, Tablet, Desktop // Playwright page object belongs to that specific browser context, so you can use it to interact with the browser. // To take screenshots, assign them to the screenshots object that is provided // in the script context. Screenshots captured this way are preserved even if the // script later throws — useful for debugging failed runs. screenshots[screenshot-name] await page.screenshot(); // you can save multiple screenshots and have them with different names. // when you want to return a value, use return statement with data as a prop. // To log data, use console.log // console.log(Hello World); // You can access the browser context via page.context() if needed (for example, to create a new page or dealing with popups). return { data: Hello World, };脚本要点page.goto()负责导航它是所有浏览器交互的起点console.log()输出的内容会出现在监控运行日志中是脚本调试的第一手段return { data: ... }是脚本向监控系统返回结果的标准方式返回值会被序列化为 JSON 存储browserType与screenSizeType是当前运行上下文的内置变量可用来区分不同浏览器/屏幕组合下的行为差异。返回值序列化规则脚本返回的数据在存储前会经过 JSON 序列化行为与JSON.stringify一致普通对象与数组中的NaN、Infinity会被转换为nullundefined属性与函数会被丢弃Date对象会变成 ISO 字符串类实例等非纯对象会被整体丢弃。因此建议只返回可 JSON 化的纯数据例如return { data: { loadTime } }。深入理解 Playwright 的使用边界OneUptime 使用 Playwright 模拟用户交互但脚本并不直接运行在探针的 Node.js 进程里。page是一个经过安全封装的、与 Playwright 兼容的门面对象facade常用的Page、Locator、Frame、ElementHandle、JSHandle、Request、Response、keyboard、mouse 以及 browser-context 方法均可使用涵盖导航、定位器、点击、表单输入、页面求值、弹窗、多页面、响应检查与截图等能力。这一点在 WorkerBootstrap.ts 的源码注释中有明确印证用户脚本运行在独立的浏览器 Web Worker 中所有可见对象都是 Worker 域内包含拷贝数据或不透明标识的代理数据跨越运行时边界时以拷贝或执行级能力句柄的形式传递。哪些 API 不可用出于安全隔离考虑会逃逸隔离边界的能力被有意禁用调用时会抛出带引导信息的明确错误类别不可用 API替代方案浏览器启动/连接browserType.launch()、connect()、connectOverCDP()、launchPersistentContext()无需自行启动脚本内直接使用pageCDP 会话newCDPSession()不使用请求路由page.route()、routeFromHAR()、page.request.*使用axios全局对象发起 HTTP 请求事件监听器page.on(...)、page.once(...)等使用page.waitForEvent(...)、字符串/正则匹配的请求与响应等待同步 frame 访问器page.frames()、page.mainFrame()、page.frame(...)使用page.frameLocator(...)处理 iframe私有字段/宿主路径Playwright 私有字段、读写宿主文件系统路径的选项不使用浏览器权限剪贴板、摄像头、麦克风、MIDI、本地字体等仅 geolocation 与 notifications 权限可用输出形式整页截图、PDF 输出使用视口viewport截图浏览器上下文page.context().browser()不可用几点重要细节每执行最多 8 个页面源码常量MAX_CONTEXT_PAGES 8事件、请求、响应、URL 等待方法的函数谓词无法跨越隔离边界请改用字符串或正则匹配器、定位器或显式轮询传给page.evaluate()等方法的求值函数会在被监控的浏览器页面内执行绝不会在探针进程中执行page.waitForNavigation(...)、page.setDefaultTimeout(...)、page.setDefaultNavigationTimeout(...)是受支持的。以 WorkerBootstrap.ts 为例源码中明确列出了被屏蔽的全局能力BroadcastChannel、EventSource、SharedWorker、WebSocket、Worker、XMLHttpRequest、fetch、importScripts等并把launch、connect、route、tracing等属性列入blockedProperties——脚本内的所有 HTTP 通信都应经由axios或http/https门面完成浏览器网络能力由探针统一代理。截图取证screenshots 侧通道脚本上下文中预声明了一个screenshots对象。你可以在脚本任意位置将截图赋值给它——即使脚本随后抛出异常包括断言失败、超时或意外错误这些截图依然会被保留从而精确还原运行失败时页面所处的状态。成功捕获的截图会出现在 OneUptime Dashboard 中该次监控运行的详情里。// Capture screenshots via the screenshots side-channel — they are preserved on both success and failure. await page.goto(https://app.example.com/login); screenshots[login-page] await page.screenshot(); await page.fill(#email, userexample.com); await page.fill(#password, wrong); await page.click(button[typesubmit]); // If the next assertion throws, the login-page screenshot above is still captured. await page.waitForSelector(.dashboard, { timeout: 5000 }); screenshots[dashboard] await page.screenshot(); return { data: Login succeeded, };示例中即使waitForSelector(.dashboard, { timeout: 5000 })断言失败login-page这张失败前一刻的截图仍然会被保存这是排查登录问题的最直接证据。旧式截图返回方式Legacy出于向后兼容脚本也可以把截图作为返回值的一部分返回。但这种方式只有在脚本正常结束时才会捕获截图——一旦脚本抛出异常截图就会丢失。// Legacy pattern — screenshots only captured on successful return. const screenshots {}; screenshots[screenshot-name] await page.screenshot(); return { data: Hello World, screenshots: screenshots, };需要失败现场证据时请优先使用上面的侧通道side-channel模式而不是旧式返回模式。使用 Monitor Secrets 注入敏感信息监控脚本往往需要访问 API Key、密码等敏感信息。Monitor Secrets 提供加密存储与按监控授权的注入能力避免把凭据硬编码进脚本。添加 Secret创建路径OneUptime Dashboard → Monitors → Settings → Secrets → Create Monitor Secret。创建时可以指定哪些监控monitor有权访问该 Secret。需要注意Secret 加密存储Secret 保存后无法再次查看或修改其值丢失后只能创建新 Secret需要轮换时可点击该行上的Update Secret Value按钮更新值无需删除重建。在脚本中引用 Secret在脚本中通过monitorSecrets对象引用已授权的 Secret语法为模板占位符形式// if your secret is of type string then you need to wrap it in quotes let stringSecret {{monitorSecrets.StringSecret}}; // if your secret is of type number or boolean then you can use it directly let numberSecret {{monitorSecrets.NumberSecret}}; // if your secret is of type boolean then you can use it directly let booleanSecret {{monitorSecrets.BooleanSecret}}; // you can even console log to see if the secrets is being fetched correctly console.log(stringSecret);类型规则字符串string类型的 Secret 必须用引号包裹{{monitorSecrets.StringSecret}}数字number或布尔boolean类型的 Secret 可直接使用无需引号{{monitorSecrets.NumberSecret}}。从 monitor-secrets 文档 可以确认Secret 是在探针上、在合成监控/自定义代码监控脚本执行之前被注入的因此脚本运行时{{monitorSecrets.ApiKey}}这样的引用已经解析为解密后的真实值。Secret 同样可用于 API 监控的请求头/请求体/URL、Website/IP/Port/Ping/SSL 监控的 URL以及 SNMP 监控的 community string 与 SNMPv3 认证密钥中。采集自定义指标oneuptime.captureMetric()脚本可以通过oneuptime.captureMetric(name, value, attributes)输出自定义指标这些指标被存储在 OneUptime 中可在Metric Explorer中绘制成图表用于告警与筛选。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; // Capture page load time as a custom metric oneuptime.captureMetric(dashboard.load.time, loadTime, { page: dashboard, }); screenshots[dashboard] await page.screenshot(); return { data: { loadTime }, };采集后指标会以custom.monitor.dashboard.load.time之类的名称出现在 Metric Explorer 中。你可以把它加入 Dashboard 图表、设置告警并按监控、探针、浏览器类型、屏幕尺寸或自定义属性进行筛选。指标限制单次脚本执行最多采集100条指标源码常量MAX_METRICS 100指标名称最长200字符值必须是数字在 WorkerBootstrap.ts 的oneuptime.captureMetric实现中非有限数字会直接忽略。从 WorkerBootstrap.ts 的实现可以看到每条指标最多携带 50 个属性属性键截断为 200 字符、属性值转为字符串并截断为 1000 字符指标通过 RPC 消息以captureMetric方法回传给探针侧的 PlaywrightCapabilityBroker.ts其中captureMetric位于该 Broker 支持的方法白名单中最终进入监控运行结果。脚本内可用的模块一览模块说明page与浏览器交互的安全 Playwright 兼容门面。可通过page.context()访问执行上下文以创建页面或处理弹窗浏览器启动/连接、CDP、路由、绑定、私有字段与宿主路径选项不可用screenshots预声明的对象向其赋值截图如screenshots[login-page] await page.screenshot()即使脚本后续抛出异常也会被保留axios基于 Promise 的 HTTP 客户端支持可调用式 Axios 及request、get、head、options、post、put、patch、delete、create。请求/响应大小、重定向与超时有限制自定义 transport、adapter、socket、agent 与 proxy 覆盖不可用crypto浏览器 Worker 实现的 SHA-256 哈希、HMAC-SHA-256、randomBytes、randomInt、randomUUIDconsole.log输出日志到控制台用于调试日志会出现在监控运行的日志区oneuptime.captureMetric从脚本采集自定义指标见上文自定义指标章节http仅客户端的缓冲式兼容门面支持request、get、Agenthttps与http门面对应的 HTTPS 版本从源码角度看crypto门面在 WorkerBootstrap.ts 中被刻意收窄为仅 SHA-256/HMAC-SHA-256/随机数能力createHash、createHmac、randomBytes、randomInt、randomUUID其他算法会明确抛错http/https是建立在axios之上的、仅客户端、缓冲式的事件门面。这也再次印证了合成监控能力最小化、隔离最大化的安全设计。需要特别注意的点page对象是浏览器交互的主要接口它刻意实现的是Playwright 功能的 allowlist白名单而非直接暴露裸的 Playwright 或 Node.js 对象使用console.log记录日志日志会出现在该监控的日志区使用return语句返回数据截图请赋值给预声明的screenshots对象以便脚本抛错时仍被保留使用browserType与screenSizeType变量获取当前运行上下文的浏览器类型Chromium 或 Firefox与屏幕尺寸Mobile、Tablet、Desktop可自由在脚本中使用这是 JavaScript 脚本你可以使用所有 JavaScript 语言特性使用axios模块在脚本中发起 HTTP 请求、调用 API使用 oneuptime.com 托管服务时脚本上下文总是包含最新版本的 Playwright 与浏览器自托管时请确保探针更新到最新的 Playwright 与浏览器版本脚本默认超时为60 秒可由探针运维者配置超时的 Worker 及其所有浏览器子进程都会被终止探针侧的 Limits.ts 同时定义了MAX_SYNTHETIC_MONITOR_SCRIPT_TIMEOUT_IN_MS这一脚本超时上限每次执行都有内存与可写浏览器存储的额度限制超出任一额度都会终止该次执行并清理其临时 profile自托管运维者可以在探针上配置这些上限。小结OneUptime 合成监控把真实用户路径转化为可重复、可度量、可留证的程序化脚本用page驱动浏览器完成交互用screenshots侧通道保留成功与失败两种状态下的页面证据用monitorSecrets安全注入凭据再用oneuptime.captureMetric()把业务关键耗时变成可查询、可告警的指标。配合全球多探针位置与浏览器/屏幕尺寸矩阵它适合作为应用发布后的主动健康检查与性能回归手段。更多相关能力可继续阅读 Monitor Secrets 文档或在 探针合成运行时源码 中深入其隔离与限流实现。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考