Vercel CLI 告警规则：`vc alerts rules schema` 与内置/自定义告警规则创建实战指南

CLI后端云原生【免费下载链接】vercelDevelop. Preview. Ship.项目地址https://gitcode.com/gh_mirrors/ve/vercel点击查看免费下载导读本文基于 Vercel CLI本仓库packages/cli中新增的alerts rules schema命令及其配套的规则创建示例系统讲解如何通过 CLI 以 JSON body 的形式创建、查询、更新和删除告警通知规则Alert Rules。你将掌握三种规则类型usage_anomaly、error_anomaly、custom_alert的完整字段定义与可复制示例、--project与--all作用域语义以及自定义告警查询queryJsonString从指标发现到 JSON 转义的完整链路实现与 Vercel 控制台Dashboard对齐的告警管理能力。一、背景本次变更带来了什么本次变更见 .changeset/alert-rules-schema-help.md为vercelCLI 增加了alerts rules schema子命令并补充了内置规则与自定义告警规则的创建示例。其核心改进有三点新增schema子命令开发者无需翻阅文档即可在终端查看告警规则 body 的字段定义与示例显式--project作为内置规则的目标创建内置规则时通过--project name-or-id明确指定目标项目避免依赖隐式上下文完整自定义告警项目元数据创建自定义告警规则时自动补齐scope中的projectId/projectName等项目元数据确保规则创建后可以直接在 Dashboard 中编辑。这些改动落在packages/cli/src/commands/alerts/rules/目录下与已有的ls、add、inspect、update、rm子命令共同构成一套完整的告警规则命令行管理能力源码中的rulesAggregateCommand将其描述为Create, list, update, or delete alert notification rules (dashboard parity)见 command.ts。二、alerts rules命令族速览在深入schema之前先整体认识vc alerts rules的六个子命令定义见 command.ts子命令别名作用示例lslist列出当前作用域下的告警规则可按类型过滤vc alerts rules ls --type custom_alertschema—按告警类型展示规则 body schema 与示例vc alerts rules schema --type error_anomalyaddcreate从 JSON body 文件创建规则vc alerts rules add --body ./rule.jsoninspectget按ruleId查看单条规则vc alerts rules inspect ar_abc123updatepatch从 JSON body 文件局部更新规则vc alerts rules update ar_abc123 --body ./patch.jsonrmremove、delete删除规则vc alerts rules rm ar_abc123 --yes所有子命令都共享两个作用域选项--project name-or-id简写-p指定项目作用域覆盖当前链接项目需要团队上下文--all简写-a仅操作团队级规则省略项目过滤忽略链接项目。从源码可以确认--all与--project是互斥的parseRulesFlagsAndScope会调用validateAllProjectMutualExclusivity做校验同时传入两个参数会报参数错误见 parse-scope.ts。三、vc alerts rules schema命令详解3.1 列出支持的规则类型不带任何参数运行vc alerts rules schema会以表格形式输出三种受支持的规则类型源码见 schema.tsTypeDescriptionusage_anomalyBuilt-in usage anomaly alerts内置用量异常告警error_anomalyBuilt-in error anomaly alerts内置错误异常告警custom_alertCustom Observability metric alerts自定义可观测性指标告警并提示运行vc alerts rules schema --type type查看具体规则 body schema。3.2 查看某一类型的完整 schemavc alerts rules schema --type custom_alert--type参数接受usage_anomaly、error_anomaly、custom_alert三者之一。从源码看参数会经过normalizeRuleType归一化处理会trim()、转小写并将连字符/空白替换为下划线如custom-alert或custom alert都会被识别为custom_alert见 schema.ts传入非法类型时则返回INVALID_ARGUMENTS错误并提示可用的三种类型。CLI 文本输出结构为字段表Fields→alertTypes[].filter允许值 → 自定义告警字段表 →queryJsonString字段表 → 转义前的查询 JSON 示例 → 完整 body 示例。3.3 JSON 输出模式对脚本/自动化场景可以追加--format json对应源码中的formatOptionvc alerts rules schema --type custom_alert --format json此时整个 schema 对象含type、description、fields、examples等以 JSON 形式输出到 stdout见 schema.ts便于被 jq 等工具进一步处理。四、内置规则 schemausage_anomaly 与 error_anomaly4.1 公共字段两类内置规则共享BUILT_IN_COMMON_FIELDS见 schema.tsFieldRequiredType说明nameyesstring规则名称alertTypesyesarray一个或多个告警类型配置projectIdnostringOData 项目过滤表达式省略则作用于团队级autosubscribeOwnersInKnocknoboolean是否自动订阅项目所有者4.2usage_anomaly用量异常除公共字段外alertTypes[].type固定为usage_anomaly必填alertTypes[].filter为可选的 OData 过滤表达式。filter支持的指标metric字段取值为fluid_cpu_duration, fluid_duration, fast_data_transfer, edge_requests, function_invocations最小示例团队级监控所有用量指标{ name: Usage anomalies, alertTypes: [{ type: usage_anomaly }] }过滤到单一指标的项目级示例{ name: Edge request anomalies, projectId: projectId eq prj_123, alertTypes: [{ type: usage_anomaly, filter: metric eq edge_requests }] }4.3error_anomaly错误异常结构同usage_anomalyalertTypes[].type固定为error_anomaly。filter的典型维度与取值示例FieldAllowed values / examplesstatusGroup4xx,5xxrouteroute eq /api/checkout,contains(route, /api)最小示例{ name: Error anomalies, alertTypes: [{ type: error_anomaly }] }按 5xx 状态组与路由过滤{ name: Checkout 5xx errors, projectId: projectId eq prj_123, alertTypes: [ { type: error_anomaly, filter: statusGroup eq 5xx and route eq /api/checkout } ] }五、自定义告警规则 schemacustom_alert5.1 公共字段custom_alert使用CUSTOM_ALERT_COMMON_FIELDS见 schema.ts其中projectId是可选的默认取--project或当前链接项目FieldRequiredType说明nameyesstring规则名称projectIdnostring默认为--project或链接项目alertTypesyesarray一个或多个告警类型配置type为custom_alertcustomAlertyesobject自定义告警定义autosubscribeOwnersInKnocknoboolean自动订阅项目所有者5.2customAlert字段FieldRequiredType说明customAlert.queryJsonStringyesstring转义后的查询 JSON 字符串customAlert.triggerTypeyesstringthreshold阈值或anomaly异常检测customAlert.triggerOperatoryesstringgt,gte,lt,ltecustomAlert.triggerThresholdyesnumber阈值或 z-scorecustomAlert.minThresholdnonumber最小观测值customAlert.formulanoobject比率公式left/right 引用 rollup 键5.3queryJsonString内部字段queryJsonString本质是查询引擎query-engine查询 JSON 的转义字符串其字段为FieldRequiredType说明scopenoobject项目作用域eventyesstring告警查询事件名例如incomingRequestrollupsyesobject具名度量聚合rollups.*.measureyesstring度量指标rollups.*.aggregationyesstring聚合方式rollups.*.filternostringrollup 级 OData 过滤groupBynoarray最多一个维度filternostring顶层 OData 过滤granularitynoobject5m、1h或1d默认5m例如一个按route分组的 5 分钟请求量查询转义前源码 schema.ts{ event: incomingRequest, rollups: { requests: { measure: count, aggregation: sum } }, groupBy: [route], granularity: { minutes: 5 } }以及一个计算错误率的比率查询numerator/denominator两个 rollup 键配合formula使用见 schema.ts{ event: incomingRequest, rollups: { numerator: { measure: count, aggregation: sum, filter: httpStatus ge 500 }, denominator: { measure: count, aggregation: sum } }, granularity: { hours: 1 } }5.4 自定义告警示例异常检测Anomaly{ name: Request volume anomaly, alertTypes: [{ type: custom_alert }], customAlert: { queryJsonString: {\event\:\incomingRequest\,\rollups\:{\requests\:{\measure\:\count\,\aggregation\:\sum\}},\groupBy\:[\route\],\granularity\:{\minutes\:5}}, triggerType: anomaly, triggerOperator: gt, triggerThreshold: 3 } }阈值 比率Threshold ratio{ name: Checkout error rate, alertTypes: [{ type: custom_alert }], customAlert: { queryJsonString: {\event\:\incomingRequest\,\rollups\:{\numerator\:{\measure\:\count\,\aggregation\:\sum\,\filter\:\httpStatus ge 500\},\denominator\:{\measure\:\count\,\aggregation\:\sum\}},\granularity\:{\hours\:1}}, triggerType: threshold, triggerOperator: gt, triggerThreshold: 0.05, formula: { operator: divide, left: numerator, right: denominator }, minThreshold: 20 } }注意queryJsonString必须是转义后的 JSON 字符串。实际编写时可将上述未转义 JSON 用JSON.stringify处理后嵌入源码示例正是这样生成的见 schema.ts。5.5 自定义告警指标发现schema命令的 help 部分提供了指标发现指引见 schema-help.ts运行vc metrics schema metric-or-prefix可以发现可用指标、聚合与维度指标 ID 使用vercel.命名空间如vercel.request.count自定义告警查询使用 query-engine 的 event/measure 名称而非公开指标 ID映射关系如下公开指标 IDeventmeasurevercel.request.countincomingRequestcountvercel.function_invocation.countserverlessFunctionInvocationcountvercel.external_api_request.countoutgoingRequestcountvercel.sandbox.cpu_total_time_mssandboxUsagecpuTotalTimeMs六、规则创建实战vc alerts rules add6.1 完整的内置规则示例以下示例直接来自 CLI 帮助文本见 add-help.ts。显式指定项目的内置用量异常规则注意--project用法与projectId使用in运算符{ name: Production usage anomalies, alertTypes: [{ type: usage_anomaly }], projectId: projectId in (prj_123), autosubscribeOwnersInKnock: true }内置 4xx 错误异常规则{ name: Production 4xx error anomalies, alertTypes: [{ type: error_anomaly, filter: statusGroup eq 4xx }], projectId: projectId in (prj_123) }6.2 自定义阈值规则与异常规则自定义阈值规则错误率 5%基于比率公式{ name: Checkout error rate, alertTypes: [{ type: custom_alert }], customAlert: { queryJsonString: {\event\:\incomingRequest\,\rollups\:{\errors\:{\measure\:\count\,\aggregation\:\sum\,\filter\:\httpStatus ge 500\},\requests\:{\measure\:\count\,\aggregation\:\sum\}},\granularity\:{\hours\:1}}, triggerType: threshold, triggerOperator: gt, triggerThreshold: 0.05, formula: { operator: divide, left: errors, right: requests }, minThreshold: 20 } }自定义异常规则请求量 z-score 3{ name: Edge request volume anomaly, alertTypes: [{ type: custom_alert }], customAlert: { queryJsonString: {\event\:\incomingRequest\,\rollups\:{\requests\:{\measure\:\count\,\aggregation\:\sum\}},\groupBy\:[\route\],\granularity\:{\minutes\:5}}, triggerType: anomaly, triggerOperator: gt, triggerThreshold: 3 } }6.3 执行创建命令将上述任一 body 保存为 JSON 文件如rule.json替换占位符后运行vc alerts rules add --body ./rule.json也可以显式指定目标项目vc alerts rules add --project my-app --body ./rule.json从源码add.ts可以确认整个创建流程解析参数并校验--body必填解析作用域--project/--all互斥校验读取并JSON.parsebody 文件文件不存在或 JSON 非法会给出明确错误若 body 是自定义告警规则会解析customAlert.queryJsonString校验其合法性非法 JSON 会提示Provide queryJsonString as an escaped JSON string见 custom-alert-query.ts自动删除id与teamId——这两个字段由 API 分配不应手动传入POST 到/alerts/v2/alert-rules?teamId...projectId...路径构造见 util.ts。6.4 自定义告警项目元数据的自动补齐这是本次变更的亮点之一。对于自定义告警规则若 body 中未提供projectIdCLI 会将其默认到--project或链接项目见 add.ts并进一步通过setMissingCustomAlertProjectScope向queryJsonString内的scope注入完整的项目元数据{ type: project, ownerId: teamId, projectIds: [projectId], projectId: projectId, projectName: projectName }其中projectName通过resolveCustomAlertProjectName按项目名或 ID 解析获得见 custom-alert-query.ts。补齐这些元数据后规则在 Vercel Dashboard 中可以直接展示和编辑不会出现项目信息缺失的问题。6.5 查看、更新与删除创建完成后用以下命令管理规则命令定义见 command.ts# 列出当前项目的规则 vc alerts rules ls # 列出团队级规则 vc alerts rules ls --all # 按类型过滤 vc alerts rules ls --type custom_alert # JSON 输出便于脚本处理 vc alerts rules ls --json # 查看单条规则 vc alerts rules inspect ar_abc123 # 局部更新省略的字段保持不变null 清除可选的受支持字段 vc alerts rules update ar_abc123 --body ./patch.json # 删除--yes 跳过确认 vc alerts rules rm ar_abc123 --yes七、底层实现与错误处理7.1 API 端点规则相关的 API 路径统一由 util.ts 构造集合路径GET/POST /alerts/v2/alert-rules?teamIdidprojectIdid单项路径GET/PATCH/DELETE /alerts/v2/alert-rules/ruleId?teamIdid。projectId查询参数仅在项目作用域下追加团队级--all规则省略该参数。7.2 常见错误与排查建议handleRulesApiError见 util.ts对不同的 HTTP 状态码给出了针对性提示401 / 403当前身份无权管理该作用域的告警规则。建议确认角色是否具备管理 Alert Rules 的权限必要时通过--token与--scope指定身份可用vc whoami确认当前用户与团队若规则属于其他团队则使用--scope team-slug5xx告警规则端点服务异常可加--debug重跑并附带失败请求的x-vercel-id反馈排查404规则不存在对应NOT_FOUND原因码429触发限流rate_limited其他透出serverMessage。此外--body文件不可读、JSON 非法、--project缺少参数等场景均有专门的错误提示见emitRulesArgParseError交互模式下会输出到 stderr非交互模式则输出 JSON 到 stdout 并返回退出码 1便于 CI 集成。八、最佳实践小结先 schema 后编写创建规则前先运行vc alerts rules schema --type type文本或--format json获取当前版本支持的字段与示例避免手写过时结构内置规则显式指定项目使用--project name-or-id明确目标项目或通过--all声明团队级规则不要依赖模糊的隐式上下文自定义规则注意转义queryJsonString是转义后的 JSON 字符串先用JSON.stringify处理查询对象再嵌入 body若提示 Invalid JSON优先检查转义不传id/teamId这两个字段由 API 分配CLI 会自动删除 body 中的多余值让 CLI 补齐元数据自定义告警的projectId缺省即取--project/链接项目scope项目元数据会自动补齐保证 Dashboard 可编辑。通过以上命令与示例你可以在不改动仓库代码的前提下用 Vercel CLI 完成从内置用量/错误异常告警到自定义可观测性指标告警的全流程管理。相关源码与帮助文本可进一步查阅 schema.ts、add-help.ts、add.ts 与 command.ts。赞分享CLI后端云原生【免费下载链接】vercelDevelop. Preview. Ship.项目地址https://gitcode.com/gh_mirrors/ve/vercel点击查看免费下载相关推荐Nacos告警规则自定义预警设置Nacos告警规则自定义预警设置 1. 痛点与解决方案 在微服务架构中配置中心的异常往往导致级联故障。当Nacos服务器出现配置推送失败、数据同步延迟或存储后端微服务配置中心服务注册发现云原生如何快速获取电子课本tchMaterial-parser完整使用指南如何快速获取电子课本tchMaterial parser完整使用指南 在教育数字化快速发展的今天国家中小学智慧教育平台为师生提供了丰富的电子教材资源但这些网页爬虫教育DolphinScheduler告警系统自定义告警规则与通知DolphinScheduler告警系统自定义告警规则与通知 痛点场景为什么需要强大的告警系统 在大数据任务调度场景中你是否遇到过这些问题 凌晨3点任任务调度数据编排工作流自动化后端大数据上一篇如何用Fillinger脚本10分钟搞定原本需要2小时的设计填充任务下一篇告别锁竞争Kotlin Native无锁编程实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考