OneUptime 事件与告警动态模板实战用{{变量}}占位符自动填充 Incident 与 Alert 标题、描述和修复备注【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文是 OneUptime 监控平台中Incident事件与 Alert告警动态模板Dynamic Templating的完整实战指南。当监控条件Monitor Criteria命中并自动创建事件与告警时你可以借助与监控条件中 JavaScript 表达式完全一致的{{variable}}占位符语法把监控探针采集到的真实数据响应体、状态码、耗时、系统指标、证书信息、SNMP OID 值等动态填充进事件/告警的标题、描述与修复备注Remediation Notes从而让每一条告警天然携带排障所需的上下文。读完本文你将掌握各监控类型可用的全部模板变量、基础与高级写法含{{#each}}循环、完整的实战示例以及这套模板系统在 OneUptime 源码中的实现原理。模板系统是如何工作的从源码结构看OneUptime 的事件/告警模板渲染由两个核心模块协同完成Common/Server/Utils/Monitor/MonitorTemplateUtil.ts 中的buildTemplateStorageMap()负责按监控类型构建模板变量存储映射storage map。它根据monitorType把探针返回的DataToProcess探针探测结果转换成一组键值对——例如 Website/API 监控暴露responseBody、responseStatusCode、responseTimeInMsServer 监控则把 CPU、内存、磁盘、进程指标逐项映射为模板变量。Common/Server/Utils/VM/VMAPI.ts 中的replaceValueInPlace()/expandEachLoops()负责占位符替换与循环展开。其中expandEachLoops()专门实现了{{#each path}}...{{/each}}块语法支持{{index}}、{{this}}、嵌套循环与作用域回退。MonitorTemplateUtil.processTemplateString()把两者串起来先读取用户填写的事件/告警模板字符串调用VMUtil.replaceValueInPlace(storageMap, value, false)完成替换最终返回渲染后的文本。这套逻辑同时服务于 Incident 与 Alert 的自动创建流程保证两条链路使用同一套变量体系。关于占位符语法本身它与 javascript-expression.md 中监控条件所用的 JavaScript 表达式同源嵌套对象用点号访问{{responseBody.error.id}}数组支持下标索引{{responseBody.users[0].name}}变量解析由VMUtil.deepFind()完成。支持的监控类型与限制以下监控类型支持动态模板每种类型暴露各自的变量集Website 与 API 监控响应数据、响应头、状态码、耗时Incoming Request入站请求监控请求数据、请求头、方法、时间Ping 监控连通性状态、响应时间、失败原因Port端口监控端口连通性、响应时间、超时状态IP 监控IP 可达性、Ping 时间、失败信息SSL 证书监控证书详情、校验状态、过期信息Server/VM 监控系统指标CPU、内存、磁盘、进程、主机名Synthetic合成监控脚本执行结果、截图、浏览器详情自定义 JavaScript 代码监控执行结果、耗时、错误信息Network DeviceSNMP监控设备可达性、SNMP Walk 时间、OID 值Database Health数据库健康监控连接状态、引擎版本、指标组采集情况注意Logs日志、Traces链路追踪与 Metrics指标监控当前不支持事件/告警模板因为它们使用不同的触发机制。Website 与 API 监控变量变量说明类型responseBody响应体对象。若为 HTML/XML 则是字符串若为 JSON 则是 JSON 对象string或JSONresponseHeaders响应头对象键已转为小写DictionarystringresponseStatusCodeHTTP 响应状态码numberresponseTimeInMs响应时间毫秒numberisOnline监控是否被视为在线boolean在 MonitorTemplateUtil.ts 中responseBody会先尝试用JSON.parse解析解析成功则作为 JSON 对象注入失败如 HTML 页面则按原始字符串注入——这正是上表中string或JSON两种类型的来源。Incoming Request入站请求监控变量变量说明类型requestBody请求体对象string或JSONrequestHeaders请求头对象键已转为小写DictionarystringrequestMethod入站请求的 HTTP 方法GET、POST 等stringincomingRequestReceivedAt入站请求被接收的日期时间Date当监控条件开启了Group incidents and alerts by a payload field按负载字段分组事件与告警时提取出的分组键也会作为模板变量暴露变量名取自分组路径的最后一个段。例如按requestBody.alerts[*].labels.alertname分组你就得到{{alertname}}按requestBody.alerts[*].fingerprint分组则得到{{fingerprint}}。完整的requestBody依旧同时可用。注意[*]只在分组路径字段本身中被识别——在标题/描述模板里它不会被解析占位符会原样输出连同花括号。在标题或描述中{{requestBody.alerts[0].annotations.summary}}永远读取 payload 中的第一条告警而不是事件所针对的那一条。请改用分组变量和 payload 的共享字段commonLabels、commonAnnotations。详见 incoming-request-monitor.md。Ping 监控变量变量说明类型isOnlinePing 目标是否被视为在线booleanresponseTimeInMsPing 响应时间毫秒numberfailureCausePing 失败的原因stringisTimeoutPing 请求是否超时booleanPort端口监控变量变量说明类型isOnline端口是否被视为在线/可访问booleanresponseTimeInMs连接总时间DNS 解析 TCP 连接毫秒numberfailureCause端口检查失败的原因stringisTimeout端口连接是否超时booleanIP 监控变量变量说明类型isOnlineIP 地址是否被视为在线booleanresponseTimeInMsPing 响应时间毫秒numberfailureCauseIP 检查失败的原因stringisTimeoutIP Ping 请求是否超时boolean在 MonitorTemplateUtil.ts 中Ping、Port、IP 三类监控共用同一套存储映射构建逻辑因此三者的变量集保持一致。SSL 证书监控变量变量说明类型isOnlineSSL 证书检查是否成功booleanisSelfSigned证书是否为自签名booleancreatedAt证书创建日期DateexpiresAt证书过期日期DatecommonName证书的 Common NameCNstringorganizationalUnit证书的组织单位OUstringorganization证书的组织Ostringlocality证书的所在地Lstringstate证书的州/省STstringcountry证书的国家CstringserialNumber证书序列号stringfingerprint证书的 SHA-1 指纹stringfingerprint256证书的 SHA-256 指纹stringfailureCauseSSL 检查失败的原因string以上证书字段来自探针探测结果中的sslResponse对象源码见 MonitorTemplateUtil.ts未采集到的字段以undefined注入渲染时保持原样。Server/VM 监控变量变量说明类型hostname被监控服务器的主机名stringrequestReceivedAt服务器监控请求被接收的日期时间DatecpuUsagePercentCPU 使用率百分比numbercpuCoresCPU 核心数numbermemoryUsagePercent内存使用率百分比numbermemoryFreePercent内存空闲率百分比numbermemoryTotalBytes内存总量字节numberdiskMetrics所有挂载磁盘的指标数组ArrayObjectdiskMetrics[].diskPath磁盘挂载点路径stringdiskMetrics[].usagePercent该挂载点的磁盘使用率百分比numberdiskMetrics[].freePercent该挂载点的磁盘空闲率百分比numberdiskMetrics[].totalBytes该挂载点的磁盘总空间字节numberprocesses服务器上运行的进程数组ArrayObjectprocesses[].pid进程 IDnumberprocesses[].name进程名stringprocesses[].command启动进程所用的命令stringfailureCause服务器检查失败的原因string从源码看MonitorTemplateUtil.tsCPU、内存、磁盘、进程均为按需注入只有basicInfrastructureMetrics中存在对应指标时cpuUsagePercent、diskMetrics、processes等变量才会被写入存储映射。磁盘与进程数据还会被映射为便于模板消费的结构如diskPath/usagePercent/freePercent/totalBytes与pid/name/command。Synthetic合成监控变量合成监控会在多个浏览器Chromium、Firefox、Webkit与多种屏幕尺寸移动端、平板、桌面下运行同一脚本每种配置产出一条响应。每次运行都通过syntheticResponses数组暴露——你可以按索引访问某次特定运行{{syntheticResponses[0].browserType}}也可以用{{#each syntheticResponses}}迭代所有运行。变量说明类型failureCause合成检查失败的原因stringsyntheticResponses数组脚本每针对一种浏览器/屏幕尺寸组合运行一次即含一条记录ArrayObjectsyntheticResponses[].executionTimeInMs本次运行的执行时间毫秒numbersyntheticResponses[].result本次运行返回的结果string、number、boolean或JSONsyntheticResponses[].scriptError本次运行期间发生的错误stringsyntheticResponses[].logMessages本次运行期间产生的日志消息ArraystringsyntheticResponses[].screenshots本次运行期间捕获的截图ObjectsyntheticResponses[].browserType本次运行使用的浏览器stringsyntheticResponses[].screenSizeType本次运行使用的屏幕尺寸string自定义 JavaScript 代码监控变量变量说明类型executionTimeInMs执行自定义代码所用的时间毫秒numberresult自定义代码返回的结果string、number、boolean或JSONscriptError代码执行期间发生的错误stringlogMessages执行期间生成的日志消息数组ArraystringNetwork DeviceSNMP监控变量变量说明类型isOnline设备是否可达——通过 ping或SNMP 判断。每次轮询都会设置booleanresponseTimeInMsSNMPwalk的响应时间毫秒——绝不是 ping 的往返时间numberfailureCauseSNMP walk 失败的原因stringisTimeoutSNMP walk 是否超时booleanoidResponsesOID 响应对象数组含 oid、name、value、typeArrayObjectoidResponses[].oid被查询的 OIDstringoidResponses[].nameOID 的友好名称若提供stringoidResponses[].valueOID 返回的值string或numberoidResponses[].type值的 SNMP 数据类型string{{OID_NAME}}按名称直接访问 OID 值如{{sysUpTime}}string或numbersysNameSNMP system 组中的设备名stringsysDescrSNMP system 组中的设备描述stringsysObjectId厂商注册的企业 OID设备指纹stringsysLocationSNMP system 组中的设备位置stringdownInterfaces管理上启用但运行上宕机的接口结构为{name, alias, interfaceIndex}。需要启用接口监控ArrayObjectinterfacesTotal被 walk 的接口总数numberinterfacesUp管理与运行状态均为 up 的接口数numberinterfacesDown管理上 up 但运行上 down 的接口数numberinterfaceWalkFailure接口 walk 失败时的错误消息stringtrapOidTrap OID——仅在检查由 SNMP trap 触发时设置stringtrapSourceIp接收 trap 的源 IP——仅 trap 触发检查stringtrapVarbindsTrap 携带的 varbinds结构为{oid, value}——仅 trap 触发检查ArrayObject关于 ping-only 设备的重要说明网络设备每次轮询都会执行 ping只有配置了凭据时才执行 SNMP walk因此isOnline是 ping-only 设备唯一会被填充的变量——其余所有变量都来自 SNMP walk没有凭据时它们会渲染为空白。在为可能没有凭据的设备设计模板时请把{{isOnline}}和设备自身名称放在模板最前面。关于每次轮询究竟采集什么参见 network-device-monitor.md。在 MonitorTemplateUtil.ts 中可以看到这些变量的完整构建逻辑OID 响应既被塞入oidResponses数组也会按name作为独立键注入存储映射便于直接{{sysUpTime}}接口统计遵循“管理上关闭的接口不计入故障”的语义trap 载荷仅在检查由 trap 触发时注入。Database Health数据库健康监控变量变量说明类型isOnline探针能否连接并运行基线查询。缺失指标不会使该值变为 falsebooleanresponseTimeInMs连接并运行基线查询的时间numberfailureCause检查失败的原因stringconnectionError经过净化的连接错误。绝不包含凭据或连接字符串stringengineVersion数据库服务器报告的版本字符串stringcollectedGroups本次检查产生值的指标组ArraystringunavailableGroups无法采集的组结构为{group, reason, message, remediation}ArrayObjectcollectionIssueSummary汇总所有不可用组的一行文本可直接粘贴进告警stringmetrics按序列名索引的采集值例如{{metrics[oneuptime.monitor.database.connections.used.percent]}}Object防御式模板建议未被采集的指标在metrics中是缺席absent而非 0因此当目标数据库某个指标组可能不可用时请用{{#if metrics.[...]}}做防御式模板化。基本用法在监控条件实例Monitor Criteria内部的事件/告警表单中你可以直接编写模板字符串。例如在标题字段中写API returned {{responseStatusCode}} in {{responseTimeInMs}}ms假设监控响应状态码为502、耗时为842那么保存下来的事件标题就是API returned 502 in 842ms嵌套 JSON 访问与 JavaScript 表达式完全相同Problem ID: {{responseBody.error.id}} Message: {{responseBody.error.message}}数组索引同样受支持First User: {{responseBody.users[0].name}}缺失路径的行为如果某个路径不存在占位符会原样保留在输出中——{{responseBody.error.id}}会带着花括号逐字出现在事件标题里。唯一例外是{{#each}}块如果循环路径缺失整个{{#each}}...{{/each}}块会被移除。这一行为在 VMAPI.ts 中体现为“变量未在 storage map 中找到时跳过替换”并有对应测试用例验证见下文测试章节。高级用法访问数组元素First disk usage: {{diskMetrics[0].usagePercent}}% Last process: {{processes[-1].name}}[0]取首个元素[-1]取最后一个元素。deepFind对[last]这类访问器有专门支持在缺失键时返回undefined而不是抛错。嵌套对象访问Error message: {{responseBody.error.details.message}} Server location: {{sslCertificate.locality}} {{sslCertificate.country}}用{{#each}}遍历数组当数据包含元素列表、且你希望把每个元素都写进事件或告警描述时可以使用{{#each path}}...{{/each}}块语法。语法{{#each arrayPath}} ...循环体使用每个元素的 {{property}}... {{/each}}在循环体内{{propertyName}}相对于当前数组元素解析{{nested.property}}点号访问作用于当前元素{{index}}解析为当前迭代的 0 起始索引{{this}}解析为当前元素值对字符串/数字数组很有用当前元素上找不到的变量会回退到父级存储映射示例 —— 含告警数组的入站请求如 Grafana webhook假设入站请求体如下{ status: firing, alerts: [ { status: firing, labels: { label: Coralpay } }, { status: firing, labels: { label: capitecpay } }, { status: resolved, labels: { label: capricorn } } ] }你可以编写这样的模板Alert Labels: {{#each requestBody.alerts}} - {{labels.label}} ({{status}}) {{/each}}渲染结果为Alert Labels: - Coralpay (firing) - capitecpay (firing) - capricorn (resolved)示例 —— 服务器磁盘指标Disk Usage: {{#each diskMetrics}} - {{diskPath}}: {{usagePercent}}% used {{/each}}示例 —— 使用{{index}}Processes: {{#each processes}} {{index}}. {{name}} (PID: {{pid}}) {{/each}}示例 —— 原始类型数组与{{this}}Log messages: {{#each logMessages}} - {{this}} {{/each}}示例 —— 嵌套循环你可以为多层数组嵌套{{#each}}块{{#each requestBody.groups}} Group: {{name}} {{#each members}} - {{id}}: {{role}} {{/each}} {{/each}}注意如果路径解析结果不是数组整个{{#each}}...{{/each}}块会从输出中移除。空数组则对该块不产生任何输出。这一行为的底层实现在 VMAPI.ts 的expandEachLoops()中它通过统计嵌套深度定位配对的外层{{#each}}/{{/each}}用deepFind解析数组路径非数组路径直接整块删除对每个元素构建“当前元素属性合并到父级映射”的作用域映射这正是“元素属性可直接访问、父级属性仍可回退”的实现来源并设置了最大 100 次迭代的安全上限以防止无限循环。实战示例库以下示例覆盖了各种监控类型的事件标题与描述写法可直接复制到监控条件的事件/告警表单中使用。Website/API 监控事件标题High latency: {{responseTimeInMs}}ms ( threshold)Website/API 监控事件描述### API Error Status: **{{responseStatusCode}}** Latency: **{{responseTimeInMs}}ms** Body Snippet: {{responseBody.error.message}}入站请求告警标题Bad inbound request: method{{requestMethod}} auth{{requestHeaders.authorization}}SSL 证书告警标题SSL Certificate expiring: {{commonName}} expires {{expiresAt}}服务器监控告警描述### Server Alert: {{hostname}} CPU Usage: **{{cpuUsagePercent}}%** Memory Usage: **{{memoryUsagePercent}}%** First Disk Usage: **{{diskMetrics[0].usagePercent}}%** Last Check: {{requestReceivedAt}}Ping 监控告警标题Ping failed for target: {{failureCause}} ({{responseTimeInMs}}ms)Port 监控告警描述Port connectivity issue Target port status: {{isOnline}} Total connection time (DNS TCP): {{responseTimeInMs}}ms Failure cause: {{failureCause}}合成监控告警按索引访问某次特定的浏览器/屏幕尺寸运行First run: {{syntheticResponses[0].browserType}} / {{syntheticResponses[0].screenSizeType}} Result: {{syntheticResponses[0].result}} in {{syntheticResponses[0].executionTimeInMs}}ms用{{#each}}迭代所有浏览器/屏幕尺寸组合### Synthetic Monitor Results {{#each syntheticResponses}} - **{{browserType}} / {{screenSizeType}}**: {{result}} in {{executionTimeInMs}}ms - Script error: {{scriptError}} - First log: {{logMessages[0]}} {{/each}}自定义代码监控告警Custom code execution: {{executionTimeInMs}}ms Log output: {{logMessages[0]}}网络设备监控告警标题下面三个示例假设设备配置了 SNMP 凭据——除{{isOnline}}外所有变量都来自 SNMP walk在 ping-only 设备上会渲染为空白。SNMP walk failing: {{failureCause}} ({{responseTimeInMs}}ms)网络设备监控告警描述### SNMP Device Alert Status: **{{isOnline}}** Response Time: **{{responseTimeInMs}}ms** System Uptime: {{sysUpTime}} System Name: {{sysName}} First OID Value: {{oidResponses[0].value}}入站请求 数组循环Grafana Webhook标题[{{requestBody.status}}] {{requestBody.receiver}}描述### Alerts from {{requestBody.receiver}} {{#each requestBody.alerts}} **Alert {{index}}**: {{labels.alertname}} - Label: {{labels.label}} - Status: {{status}} - Values: {{valueString}} - Source: {{generatorURL}} {{/each}}服务器监控 磁盘循环描述### Server Alert: {{hostname}} CPU Usage: **{{cpuUsagePercent}}%** Memory Usage: **{{memoryUsagePercent}}%** **Disk Usage:** {{#each diskMetrics}} - {{diskPath}}: {{usagePercent}}% used ({{freePercent}}% free) {{/each}} **Running Processes:** {{#each processes}} - [{{pid}}] {{name}}: {{command}} {{/each}}网络设备监控 OID 循环描述### SNMP Device Status Online: {{isOnline}} Response: {{responseTimeInMs}}ms **OID Values:** {{#each oidResponses}} - {{name}} ({{oid}}): {{value}} {{/each}}模板引擎的边界行为与实现细节几个容易踩坑的边界行为在源码中都有明确实现与测试保障未解析占位符原样输出变量在存储映射中不存在时replaceValueInPlace会跳过替换花括号原样保留。测试用例 leaves the braces in place 明确锁定了该行为见 Common/Tests/Server/Utils/VM/VMAPISubstitution.test.ts。$特殊字符不触发替换模式替换使用函数形式而非字符串形式因此解析出的值中的$、$、$不会被当成String.replace的替换模式测试 does not treat$ in a value as a substitution pattern。如果你在模板中引用包含美元符号的响应值可以放心使用。JSON 场景下的转义当模板处于 JSON 语境如isJSONtrue或输入为对象时解析值中的引号、换行、反斜杠、正则等会被正确转义避免破坏外层 JSON 结构。[-1]与[last]访问器deepFind支持取数组末尾元素缺失时返回undefined而非抛错。循环安全上限expandEachLoops有 100 次迭代上限与未配对标签的清理逻辑防止畸形模板导致无限循环。最佳实践小结优先使用分组变量在按 payload 字段分组的入站请求监控中标题/描述应使用分组变量如{{alertname}}与共享字段commonLabels、commonAnnotations而不是依赖requestBody.alerts[0]——后者永远指向 payload 第一条告警。对可选数据做防御式处理对 Server 监控的 CPU/磁盘/进程、SNMP 的 OID 值、数据库监控的指标组等可能缺失的数据使用{{#each}}或先决条件判断避免模板因缺失路径而渲染出尴尬的原样占位符。区分 ping-only 与带凭据的 SNMP 设备网络设备模板应以{{isOnline}}和设备名打头其余 walk 相关变量放在后面保证无凭据设备也能得到可读告警。让描述承载循环数组类数据告警列表、磁盘、进程、OID天然适合放进描述字段用{{#each}}展开标题字段保持一行关键信息即可。至此你已经掌握了 OneUptime 动态模板的全部变量、语法与底层原理可以直接在监控条件中构建带完整上下文的事件与告警通知。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考