OneUptime 自定义代码监控器（Custom Code Monitor）实战指南：脚本编写、安全密钥与自定义指标采集

OneUptime 自定义代码监控器Custom Code Monitor实战指南脚本编写、安全密钥与自定义指标采集【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime自定义代码监控器Custom Code Monitor是 OneUptime 中允许你用 JavaScript 脚本自定义监控逻辑的能力适用于现有监控器无法覆盖的场景——例如需要多步骤串联的 API 请求、带鉴权头的复杂探测、以及面向业务指标的定制检查。读完本文你将掌握脚本的编写与执行模型、Monitor Secrets 密钥的创建与注入方式、oneuptime.captureMetric()自定义指标的采集与查询以及脚本运行环境的模块、超时与安全边界。为什么需要自定义代码监控器OneUptime 内置的 HTTP、API、Website 等监控器覆盖了常见的单次请求 状态码/响应时间判定场景。但当你的探测逻辑变成这样时内置监控器就无能为力了多步骤 API 流程先登录换取 token再用 token 调用业务接口最后校验返回数据带复杂签名的请求需要先用crypto对请求体做 HMAC 签名才能访问受保护接口业务指标采集不只是通不通而是要把响应里的延迟、队列深度等数值持续上报到监控平台。自定义代码监控器就是把一段 JavaScript 脚本交给 OneUptime 的探针Probe在沙箱中执行从而用代码表达任意监控逻辑。它的核心入口在 Probe/Utils/Monitors/MonitorTypes/CustomCodeMonitor.ts其中CustomCodeMonitor.execute()接收监控 ID 与脚本源码将脚本交给 V8 沙箱运行并返回执行结果日志、采集到的指标、脚本错误、执行耗时与返回值。第一个自定义代码监控脚本官方文档给出的最小示例非常直白在脚本中直接使用axios发送 HTTP 请求用return返回数据。// 可以直接使用 axios 模块 await axios.get(https://api.example.com/); // axios 文档https://axios-http.com/docs/intro return { data: Hello World, // 在这里返回你想要的数据 };几点需要理解的行为axios是脚本内可直接使用的全局模块它是 promise 风格的 HTTP 客户端支持get、post、put、patch、delete、head、options等方法也支持axios.request()与axios.create()。需要说明的是脚本内可用的是沙箱提供的 axios 能力桥详见后文脚本运行环境一节其 API 与官方 axios 保持一致。return语句用于返回监控结果。CustomCodeMonitor.execute()会把returnValue.data写入监控响应见 Probe/Utils/Monitors/MonitorTypes/CustomCodeMonitor.ts 中scriptResult.result result?.returnValue?.data;一行因此返回什么直接决定这条监控记录的业务数据。console.log会进入监控日志可用于脚本调试日志可在探针侧查看OneUptime 界面中 Probe View Logs。脚本抛出异常时不会导致探针崩溃CustomCodeMonitor.execute()会把脚本错误捕获并写入scriptResult.scriptError脚本自身的异常被标记为外部故障EXTERNAL_FAULT记录日志而监控框架可以据此判定监控失败Error 型判定条件依然生效。使用 Monitor Secrets 安全注入密钥把 API Key、密码直接写死在脚本里显然不可取——脚本会被保存进数据库、被日志打印、被团队成员查看。OneUptime 提供Monitor Secrets机制把敏感值加密保存只在脚本执行时注入。创建 Monitor Secret在 OneUptime 的导航中进入Dashboard → 监控器Monitors→ 设置Settings→ 密钥Secrets→ 创建监控密钥Create Monitor Secret即可创建密钥从创建界面可以看到 Monitor Secret 的核心要素名称Name密钥在脚本中的引用名例如ApiKey。在数据模型中该字段为项目内唯一UniqueColumnBy(projectId)见 Common/Models/DatabaseModels/MonitorSecret.ts同名密钥在同一项目下不可重复值Value实际的敏感内容如sk_test_...形式的 API Key描述Description可选的辅助说明例如API Key for GitHub关联监控器Monitors选择哪些监控器可以访问该密钥。数据模型中通过MonitorSecretMonitor关联表JoinTable见 Common/Models/DatabaseModels/MonitorSecret.ts实现一个密钥可被多个监控器使用、一个监控器可持有多个密钥的多对多关系。重要安全提示密钥值在数据模型中被标记为encrypted: truesecretValue字段类型为VeryLongText即数据库中以密文保存、仅探针在执行监控脚本时解密使用。密钥一旦保存无法再次查看或更新只能删除后重建——丢失密钥意味着需要重新创建并重新关联监控器。在脚本中使用密钥脚本执行上下文中暴露了monitorSecrets对象你可以通过{{monitorSecrets.密钥名}}占位符引用已被授权给该监控器的密钥// 如果密钥是字符串类型需要加上引号 let stringSecret {{monitorSecrets.StringSecret}}; // 如果密钥是数字类型可以直接使用 let numberSecret {{monitorSecrets.NumberSecret}}; // 如果密钥是布尔类型也可以直接使用 let booleanSecret {{monitorSecrets.BooleanSecret}}; // 还可以用 console.log 确认密钥是否被正确注入 console.log(stringSecret);使用时有三个关键细节类型决定写法字符串密钥必须包在引号里否则注入后就是裸标识符会报语法错误数字和布尔值则直接内联。权限决定可见性占位符的解析遵循 Monitor Secret 上配置的可访问监控器授权只有被授权的监控器脚本才能拿到对应密钥。只读且隐蔽密钥是单向注入的脚本只能读取、不能写入或修改。从测试用例 Probe/Tests/Utils/MonitorUtil.test.ts 可以看到{{monitorSecrets.ApiKey}}这类占位符在探针处理 URL 时会被保留不误改说明密钥注入发生在脚本执行的独立环节避免在 URL 规范化等前置处理中被破坏。同样的机制也被 SQL 监控器等类型复用见 Probe/Utils/Monitors/MonitorTypes/SqlMonitor.ts 对{{monitorSecrets.*}}的注释。采集自定义指标oneuptime.captureMetric自定义代码监控器不仅能回答服务通不通还能产出数值型业务指标供告警和图表使用。这依赖脚本上下文中的oneuptime.captureMetric()函数oneuptime.captureMetric(name, value, attributes);三个参数的定义如下参数类型是否必填说明namestring必填指标名称例如api.response.time。上报后会自动加上custom.monitor.前缀存储valuenumber必填指标数值attributesobject可选键值对形式的附加上下文例如地域、环境等完整示例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, };上报后这些指标会出现在Metric Explorer指标浏览器中名称形如custom.monitor.api.response.time。你可以把指标加到 Dashboard 图表、为其配置告警并按监控器、探针或任意自定义属性进行筛选。底层实现与限制oneuptime.captureMetric的沙箱侧实现在 Common/Server/Utils/VM/VMRunner.ts脚本上下文中的oneuptime对象是冻结的Object.freeze调用captureMetric时通过宿主回调把名称、数值、属性 JSON传回宿主进程宿主侧会把名称截断到 200 字符、把属性解析为 JSON并累积到本次执行采集的指标列表中。指标从探针上报到服务端后会在 Common/Server/Utils/Monitor/MonitorMetricUtil.ts 中统一加工指标名会被加上custom.monitor.前缀const prefixedName: string \custom.monitor.${customMetric.name};同时写入isCustomMetric: true 以及探针 ID 等附加属性便于在指标浏览器中按来源过滤。指标采集存在以下硬性限制在沙箱侧MAX_METRICS常量与宿主回调中同时强制执行单次脚本执行最多采集 100 个指标指标名称最长 200 字符指标值必须是数值typeof value ! number或非有限数会被直接忽略。此外沙箱对指标属性做了保守清洗只接受 string/number/boolean 类型的属性值属性键截断到 200 字符、属性值截断到 1000 字符超过 50 个属性后不再处理这些阈值可以在 Probe/Utils/Monitors/SyntheticRuntime/WorkerBootstrap.ts 的captureMetric实现中看到。自定义代码监控器与合成监控器Synthetic Monitor共享同一套指标上报语义后者的测试用例如 Probe/Tests/Utils/Monitors/SyntheticRuntime/WorkerController.test.ts同样验证了captureMetric的调用路径。脚本内可用的模块官方文档明确列出的脚本可用模块如下模块/对象说明axiospromise 风格的 HTTP 客户端用于发送 HTTP 请求适用于浏览器与 Node.jscryptoNode.js 内置加密模块提供 OpenSSL 的 hash、HMAC、cipher、decipher、sign、verify 等能力的包装可用于请求签名、摘要计算等console.log向控制台输出日志用于调试日志可在监控器的日志区查看Probe View Logsoneuptime.captureMetric从脚本采集自定义指标详见上文httpNode.js 内置的 HTTP 客户端/服务器模块httpsNode.js 内置的 HTTPS 客户端/服务器模块从沙箱实现看这些能力并非原生注入而是经过受限封装axios在沙箱内是一个通过 RPC 桥接到宿主进程的代理实现见 Common/Server/Utils/VM/VMRunner.ts 的 axios 桥接代码以及 Probe/Utils/Monitors/SyntheticRuntime/WorkerBootstrap.ts 中的makeAxios请求由宿主侧的 HTTP 栈真正发出http/https模块在沙箱中被替换为Agent构造器代理真正的连接由宿主侧 axios 桥接完成crypto在沙箱环境中是一个受限实现——例如 Probe/Utils/Monitors/SyntheticRuntime/WorkerBootstrap.ts 的createCryptoFacade只开放 SHA-256 摘要、HMAC-SHA-256、randomBytes、randomInt、randomUUID等能力超出范围会直接抛错沙箱同时会屏蔽fetch、XMLHttpRequest、WebSocket、Worker、importScripts等高风险全局能力hardenAmbientCapabilities把网络出口收敛到受控的 HTTP 通道。脚本运行模型与注意事项执行生命周期自定义代码监控器的执行发生在探针Probe进程内链路为探针调度 → CustomCodeMonitor.execute() → V8 隔离沙箱runCodeInSandbox()Common/Server/Utils/VM/VMRunner.ts。执行完毕后返回日志消息列表、采集到的指标列表、脚本错误如有、执行耗时毫秒与脚本返回值。关键注意点console.log调试脚本中的日志会出现在监控器的日志区Probe View Logs是排查脚本问题的主要手段return返回数据脚本可以但非必须返回数据返回值会作为监控响应数据的一部分被保存完整的 JavaScript 能力脚本就是标准 JavaScript可用任意 JS 语法与内置对象前提是运行环境沙箱允许2 分钟超时官方文档规定脚本超时时间为 2 分钟超时后脚本会被终止。实现层面该超时由探针环境变量PROBE_CUSTOM_CODE_MONITOR_SCRIPT_TIMEOUT_IN_MS控制默认值 60000 毫秒1 分钟最小值为 1见 Probe/Config.ts。部署者可自行调整该环境变量来放宽或收紧超时VMRunner在隔离超时之外还会附加 5 秒宽限来处理挂起的宿主调用。私网访问与安全边界源码级补充自定义代码监控器与 API/Website 监控器一样在沙箱桥接层执行私网访问策略探针默认禁止访问私网地址PROBE_ALLOW_PRIVATE_NETWORK_MONITORS默认关闭见 Probe/Config.tsloopback、链路本地地址与云元数据端点无论如何都会被拒绝如果你自建探针并确实需要探测内网服务例如http://10.0.0.5/health可在探针进程设置环境变量PROBE_ALLOW_PRIVATE_NETWORK_MONITORStrue开启自动注册的全局探针由REGISTER_PROBE_KEY签发会忽略该开关始终拒绝私网地址——这是为了防止租户通过修改监控数据来放宽探针的安全策略此时提示文案会引导你部署并选用私有探针来监控私网目标。小结自定义代码监控器把监控逻辑从固定模板中解放出来用一段沙箱化的 JavaScript 表达任意探测流程通过monitorSecrets安全引用密钥用oneuptime.captureMetric()把业务数值变成可告警、可图表化的custom.monitor.*指标。理解其执行模型探针沙箱、2 分钟超时、私网访问开关与模块边界axios/http/https/crypto/console是写出可靠、安全监控脚本的前提。相关实现与配置入口均可在仓库内进一步查阅CustomCodeMonitor.ts、VMRunner.ts、MonitorSecret.ts、Probe/Config.ts。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考