OneUptime 自定义代码监控器（Custom Code Monitor）完全指南：用 JavaScript 脚本实现多步 API 探测与自定义指标采集

可观测性后端运维前端云原生微服务AI Agent【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址https://gitcode.com/GitHub_Trending/on/oneuptime点击查看免费下载本篇技术指南以 OneUptime 的 Custom Code Monitor自定义代码监控器为主题完整讲解如何编写自定义 JavaScript 脚本监控应用、接入加密的 Monitor Secrets监控密钥、通过oneuptime.captureMetric()采集自定义指标并接入 Metric Explorer同时结合仓库源码揭示脚本沙箱的隔离机制、资源限制与安全边界。阅读完本文后你将能够从零编写、调试并安全地发布一个生产可用的自定义代码监控脚本。什么是 Custom Code MonitorOneUptime 内置了大量开箱即用的监控器HTTP、Ping、SSL、端口、浏览器等但真实业务中总有一些「现有监控器做不到」的场景。Custom Code Monitor 正是为此设计它允许你在监控器中直接编写一段自定义 JavaScript 脚本用任意逻辑探测你的应用。典型场景包括多步 API 请求先登录换取 Token再携带 Token 访问业务接口现有单次 HTTP 监控无法表达这种依赖关系复杂的断言与计算拉取响应后做数据校验、计算延迟、判断队列深度是否超阈值调用 Node.js 能力使用crypto对请求签名例如生成 HMAC 鉴权头、使用内置http/https或axios发起任意 HTTP 请求采集业务指标把脚本运行时观测到的数值通过oneuptime.captureMetric()上报为自定义指标。从源码结构看Custom Code Monitor 属于探针端Probe的「合成运行时」体系用户脚本并不会直接在探针进程里执行而是被投递到由 WorkerBootstrap.ts 生成的独立 Web Worker 沙箱中运行。脚本能够访问哪些对象、哪些能力被屏蔽、数据如何回传全部由这套运行时严格定义。快速上手第一个自定义代码监控脚本一个最简的 Custom Code Monitor 脚本如下与官方文档示例一致// You can use axios module. await axios.get(https://api.example.com/); // Axios Documentation here: https://axios-http.com/docs/intro return { data: Hello World, // return any data you like here. };几点说明脚本以async 函数体执行因此可以直接await任何 Promiseaxios是运行时预置的全局模块无需import/require通过return返回任意数据该数据会被序列化并作为本次监控执行的结果保存执行完成后监控器会依据是否抛出异常判定为「正常」或「故障」超时、未捕获异常都会导致本次探测失败。脚本沙箱运行时如何执行你的代码理解沙箱机制有助于写出更稳、更合规的脚本。在 WorkerBootstrap.ts 中可以看到用户代码被包装成AsyncFunction执行const userFunction new AsyncFunction( ...parameterNames, use strict;\nreturn await (async function () {\nuse strict;\n payload.code \n}).call(undefined);, );脚本真正能访问的只有以参数形式注入的受限对象包括page、axios、http、https、crypto、console、oneuptime、screenshots、Buffer以及几个定时器函数。与此同时运行时通过hardenAmbientCapabilities()显式屏蔽了fetch、XMLHttpRequest、WebSocket、importScripts、Worker等可能逃逸隔离边界的浏览器能力见 WorkerBootstrap.ts——所以脚本内不要使用fetch请统一使用axios或http/https。沙箱还施加了多项资源约束可在 WorkerBootstrap.ts 中看到定义约束项上限单次脚本执行采集指标数MAX_METRICS100单次请求负载大小MAX_REQUEST_BYTES1 MB执行结果大小MAX_RESULT_BYTES5 MB日志总量MAX_LOG_BYTES1 MB日志条数MAX_LOG_MESSAGES10,000 条参数/结果序列化深度MAX_SERIALIZATION_DEPTH30 层序列化节点数MAX_SERIALIZATION_NODES20,000 个此外脚本存在2 分钟超时如果脚本执行超过 2 分钟运行时会直接将其终止。这一限制在探针端 Limits.ts 中也有对应实现SYNTHETIC_MONITOR_WORKER_STARTUP_ALLOWANCE_IN_MS 120_000即 2 分钟。因此建议所有对外部服务的请求都显式设置超时避免脚本被整体掐断。使用 Monitor Secrets监控密钥当脚本需要访问 API Token、密码等敏感信息时不要硬编码在脚本里——请使用 OneUptime 的 Monitor Secrets。它专门用于在监控器中安全保存密钥其核心承诺是密钥在数据库中加密存储且只有探针Probe在执行监控时能够读取。创建密钥创建路径OneUptime Dashboard - Monitors - Settings - Secrets - Create Monitor Secret。创建时你可以选择哪些监控器有权访问该密钥例如添加一个名为ApiKey的密钥并勾选需要它的监控器。一个密钥可以同时授权给多个监控器未授权的监控器脚本无法读取它。请注意密钥是加密后安全存储的。一旦保存你无法再查看或更新它的值如果丢失只能重新创建一个新密钥。这一点在数据模型中有明确体现查看 MonitorSecret.tssecretValue字段标注了encrypted: true其描述明确写着「This value will be encrypted and only accessible by the probe.」该值将被加密且只有探针可访问。同时密钥与监控器之间通过ManyToMany关联monitors字段实现了细粒度的访问授权见 MonitorSecret.ts。在脚本中使用密钥在脚本上下文中通过monitorSecrets对象访问已授权给当前监控器的密钥。注意按类型处理引号// 字符串类型的密钥需要包在引号里 let stringSecret {{monitorSecrets.StringSecret}}; // number 或 boolean 类型可以直接使用 let numberSecret {{monitorSecrets.NumberSecret}}; // boolean 类型同样直接使用 let booleanSecret {{monitorSecrets.BooleanSecret}}; // 也可以 console.log 出来确认是否获取正确 console.log(stringSecret);要点monitorSecrets是脚本模板层的占位符机制运行时会把密钥实际值注入到对应位置。字符串型密钥必须加引号否则会变成裸标识符导致语法错误。采集自定义指标oneuptime.captureMetric()脚本运行中产生的业务数值响应延迟、队列深度、库存余量等可以通过oneuptime.captureMetric()上报为自定义指标随后在 OneUptime 的Metric Explorer指标浏览器中绘图、加入仪表盘图表、配置告警。函数签名oneuptime.captureMetric(name, value, attributes);参数类型说明namestring必填指标名称例如api.response.time。上报后会自动加上custom.monitor.前缀存储valuenumber必填指标的数值attributesobject可选附加上下文的键值对string、number、boolean 类型会被记录number 与 boolean 会以文本形式存储因为指标属性是维度而非度量其他类型一律忽略完整示例const response await axios.get(https://api.example.com/health); // 采集一个简单指标 oneuptime.captureMetric(api.response.time, response.data.latency); // 带属性的指标 oneuptime.captureMetric(api.queue.depth, response.data.queueDepth, { region: us-east-1, environment: production, }); return { data: response.data, };采集完成后这些指标会以custom.monitor.api.response.time这样的名字出现在 Metric Explorer 中。你可以把它们加入仪表盘图表、配置告警并按监控器、探针或你提供的任意自定义属性进行过滤。限制与保留属性键采集自定义指标时受以下硬性限制约束同样可以在 WorkerBootstrap.ts 的captureMetric实现中逐一验证每次脚本执行最多采集100 个指标指标名称长度上限200 个字符值必须是数字非有限数会被直接丢弃每个指标最多50 个属性属性键上限200 个字符属性值上限1000 个字符。保留属性键Reserved attribute keys以下属性名属于 OneUptime 自身所有脚本不能写入。如果脚本尝试设置该属性会被丢弃指标本身仍会记录同时一条指明该键名的告警会被写入 OneUptime 服务器日志监控器身份monitorId、projectId、monitorName、probeName、probeId、isCustomMetriconeuptime.与resource.命名空间下的所有内容——这些承载 OneUptime 在摄取时打上的标识符资源身份属性service.name、host.name、k8s.cluster.name、iot.fleet.name、proxmox.cluster.name、vmware.vcenter.name、ceph.cluster.name、docker.swarm.cluster.name。禁止覆盖这些键的原因在于它们不只是标签OneUptime 会把这些键读作「该数据点属于哪个资源」的声明。例如一个被标记为service.name: payments-api的指标会出现在该服务的 Metrics 标签页上如果你后续再基于service.name构建指标监控器它的告警会关联到该服务、分页通知该服务负责人并且在该服务的维护窗口期间保持静默。因此如果想把监控器与某个服务或主机关联请使用监控器自身的标签labels而不是在指标属性里伪造资源身份。脚本中可用的模块官方文档明确列出了脚本内置的模块能力axios基于 Promise 的 HTTP 客户端用于发起 HTTP 请求。源码中它在沙箱内通过 RPC 桥接到探针宿主实现见 WorkerBootstrap.ts支持get/post/put/patch/delete/head/options以及axios.create()自定义实例cryptoNode.js 内置加密模块的沙箱化子集提供哈希、HMAC、签名/验签等能力。注意沙箱实现createCryptoFacade仅开放 SHA-256 相关的createHash/createHmac以及randomBytes/randomInt/randomUUID使用其他算法会抛出错误console.log向控制台输出日志便于调试oneuptime.captureMetric采集自定义指标见上文httpNode.js 内置 HTTP 客户端模块沙箱化实现http.get/http.requesthttpsNode.js 内置 HTTPS 客户端模块沙箱化实现https.get/https.request。除上述模块外脚本是标准的 JavaScript 脚本你可以使用全部 JavaScript 语言特性async/await、解构、Map/Set、正则、Buffer等但必须运行在沙箱授予的能力范围内。调试与注意事项查看日志脚本中的console.log输出会出现在监控器的日志区域Probes - View Logs。遇到脚本报错时先看这里返回值使用return语句返回数据返回值会作为本次监控执行结果被记录与展示超时脚本整体超时时间为2 分钟超时会被终止。对外部 API 的请求请自行设置超时数据量限制注意 100 个指标/次、1 MB 请求负载、5 MB 返回结果、1 MB 日志等沙箱配额避免脚本因数据过大被判定失败不要使用被屏蔽的能力fetch、XMLHttpRequest、WebSocket、importScripts等在沙箱中被显式禁用一律改用axios/http/https密钥安全不要在脚本中硬编码密钥也不要console.log打印真实密钥到日志请统一使用monitorSecrets并注意字符串型密钥的引号包裹。结语Custom Code Monitor 把「监控」从固定的单次请求扩展为任意可编程逻辑配合 Monitor Secrets 的安全密钥注入与oneuptime.captureMetric()的自定义指标上报能够覆盖多步鉴权 API、复杂业务断言、自定义业务指标等真实场景。编写脚本时牢记沙箱能力边界、2 分钟超时与 100 指标/次的配额并遵守保留属性键约定即可稳定地把它纳入你的监控与告警体系。赞分享可观测性后端运维前端云原生微服务AI Agent【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址https://gitcode.com/GitHub_Trending/on/oneuptime点击查看免费下载相关推荐OneUptime 自定义代码监控器Custom Code Monitor完全指南脚本化监控、Monitor Secrets 与自定义指标OneUptime 自定义代码监控器Custom Code Monitor完全指南脚本化监控、Monitor Secrets 与自定义指标 自定义代码监控可观测性后端运维前端云原生微服务AI AgentOneUptime 自定义代码监控器Custom Code Monitor完全指南脚本、密钥与自定义指标实战OneUptime 自定义代码监控器Custom Code Monitor完全指南脚本、密钥与自定义指标实战 自定义代码监控器Custom Code M可观测性后端运维前端云原生微服务AI AgentOneUptime 自定义代码监控器Custom Code Monitor实战指南脚本编写、安全密钥与自定义指标采集OneUptime 自定义代码监控器Custom Code Monitor实战指南脚本编写、安全密钥与自定义指标采集 自定义代码监控器Custom Co可观测性后端运维前端云原生微服务AI Agent上一篇揭秘jQuery File Upload核心架构为什么它是开发者首选的上传解决方案下一篇新手入门 blessed-contrib10 分钟搞懂 blessed 与 contrib 的关系及组件运行机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考