Prometheus Alertmanager Alerts API 告警接入指南APIv2 数据格式、时间语义与客户端契约【免费下载链接】alertmanagerPrometheus Alertmanager项目地址: https://gitcode.com/GitHub_Trending/al/alertmanagerPrometheus Alertmanager 对外提供 HTTP API用于接收、查询和管理告警。其中POST /api/v2/alerts是告警写入的唯一官方通道本指南将围绕 docs/alerts_api.md 完整讲解 APIv2 的请求格式、五个核心字段labels、annotations、startsAt、endsAt、generatorURL的时间语义以及客户端应遵守的重发直到解决契约读完你既能手工用 curl 发送告警也能用amtool完成同样的工作并理解 Alertmanager 如何在无状态重启后依然保证已解决通知不丢失。一、背景为什么官方推荐由 Prometheus 推送告警官方文档首先给出一个重要提示Prometheus 负责将告警发送给 Alertmanager。在生产环境中应当优先在 Prometheus 中基于时间序列数据配置告警规则alerting rules由 Prometheus 内部机制推送告警而不是直接调用 Alerts API 手工发送。原因在于 Prometheus 针对Alertmanager 崩溃或重启做了若干特殊处理能够保证告警最终送达这是手工调用 API 无法获得的可靠性保证。APIv2 本身是一份 OpenAPI 规范定义在仓库的 api/v2/openapi.yaml 中basePath为/api/v2/consumes与produces均为application/json。官方声明 APIv1 在 Alertmanager 0.16.0 版本被标记为弃用deprecated并在 0.27.0 版本被彻底移除因此当前所有客户端都应以 APIv2 为准。二、发送告警POST /api/v2/alerts向 APIv2 发送告警只需对api/v2/alerts发起一次POST请求请求方法POST请求路径api/v2/alerts在 OpenAPI 中对应/alerts路径下的postAlerts操作请求头必须设置Content-Type: application/json请求体一个 JSON 数组数组中的每个元素代表一条告警在 OpenAPI 规范中该操作对应的请求体类型为postableAlerts即postableAlert的数组其 Go 实现位于 api/v2/models/postable_alert.go服务端处理入口为 api/v2/restapi/operations/alert/post_alerts.go。OpenAPI 中声明的响应码为200成功、400请求体非法、500内部错误。一个最小的请求体示例如下来自原文档[ { labels: { alertname: required_value, name: value, ... }, annotations: { name: value, }, startsAt: RFC3339, endsAt: RFC3339, generatorURL: value }, ... ]2.1 字段逐一解析结合 OpenAPI 定义postableAlert由startsAt、endsAt、annotations与内嵌的alert组成与源码模型各字段说明如下字段类型是否必填说明labels对象string→string必填告警的标签集合是告警身份的核心标识见 2.2annotations对象string→string可选附加的说明信息如 summary、description、runbook 链接startsAtRFC3339 时间字符串可选告警触发时间省略时由 Alertmanager 设为当前时间endsAtRFC3339 时间字符串可选告警应被解决的时刻省略时设为当前时间 resolve_timeoutgeneratorURLURI 字符串可选指向告警来源的唯一 URL如 Prometheus 中触发该告警的规则页面源码佐证在 api/v2/models/alert.go 中Alert结构体的Labels字段带Required: true校验注解GeneratorURL使用strfmt.URI类型并按uri格式校验在 api/v2/models/postable_alert.go 中StartsAt与EndsAt均为strfmt.DateTime校验时按date-time格式即 RFC3339解析格式非法会直接返回 400。2.2 labels告警去重的身份标识所有告警都拥有标签labels和注解annotations。二者的职责分工非常明确labels 用于对同一告警的重复实例进行去重deduplicate。Alertmanager 依据标签集合计算告警的指纹fingerprint相同标签的告警会被视为同一条告警的多次上报从而在通知层面去重annotations 用于携带告警的其他附加信息例如摘要summary、详细描述description或 runbook 的 URL注解不参与去重。因此发送告警时至少应携带alertname标签如示例中的required_value占位符所示并配合severity、instance等用于分组、路由和静默匹配的标签。2.3 时间戳语义RFC3339 与默认行为所有时间戳均要求使用RFC3339 格式例如2026-09-15T06:00:00Z或2026-09-15T14:00:0008:00。两个时间字段的默认行为是startsAt告警触发的时间。若省略Alertmanager 将startsAt设置为当前时间endsAt告警应当被解决的时刻。若省略Alertmanager 将endsAt设置为当前时间 resolve_timeout。resolve_timeout是全局配置项定义于 config/config.go 中的GlobalConfig.ResolveTimeoutYAML 键名resolve_timeout其语义为告警在未被更新的情况下经过多长时间后被声明为已解决。这意味着一条只发送了一次、没有指定endsAt的告警会在resolve_timeout之后自动过期并被标记为 resolved从而触发已解决通知。2.4 generatorURL溯源链接generatorURL是一个指向告警来源的唯一 URL。最典型的场景是链接到 Prometheus 中触发该告警的那条告警规则firing rule页面便于接收通知的人在告警到达时直接跳转到问题源头排查。三、客户端预期无状态设计下的重发契约原文档明确要求客户端包括 Prometheus 本身遵守以下行为约定这也是使用 Alerts API 时最容易忽略、却最关键的部分持续重发 firing 告警客户端应定期向 Alertmanager 重发处于触发firing状态的告警直到该告警被解决为止。这是 Alertmanager 无状态架构能够工作的前提——它不会主动记住某条告警而是依赖客户端持续上报来维持告警的活跃状态。重发间隔的影响因素具体重发间隔由多个变量决定例如告警自身的endsAt时间戳若endsAt被省略则取决于resolve_timeout的取值。endsAt的自动续期当客户端省略endsAt上报一条已存在的告警时Alertmanager 会把该告警的endsAt更新为当前时间 resolve_timeout。也就是说只要客户端还在持续重发告警的死亡时间就会不断被推迟告警得以持续处于 firing 状态。解决判定一条 firing 告警在其endsAt时间过去之后即被视为已解决resolved。解决后的 5 分钟重发窗口为了保证已解决告警能收到 resolved 通知客户端在告警解决之后还应当继续向 Alertmanager 重发该已解决告警持续最多 5 分钟。由于 Alertmanager 是无状态的这条约定确保即使 Alertmanager 恰好在解决时刻崩溃或重启已解决通知依然能够被补发不会丢失。从源码结构看这一整套接收 → 时间语义 → 解决判定的处理链路与 api/v2 的 API 层、provider/mem/mem.go 的内存告警存储以及resolve_timeout配置共同构成API 层负责解析与校验入站告警存储层维护告警状态而时间戳语义endsAt默认值与续期决定了告警何时从 firing 转入 resolved。四、实战用 amtool 发送告警仓库自带的amtool命令行工具封装了 Alerts API 客户端是手工发送告警最便捷的方式。其实现位于 cli/alert_add.go底层正是通过client.Alert.PostAlerts见 api/v2/client/alert/alert_client.go构造PostAlertsParams并调用 APIv2 的POST /alerts接口。添加一条最简单的告警alertname可通过首个裸参数隐式指定amtool alert add alertnamefoo nodebar amtool alert add foo nodebar # 效果同上foo 被当作 alertname 的值携带注解与自定义时间amtool alert add foo nodebar \ --annotationrunbookhttp://runbook.biz \ --annotationsummarysummary of the alert \ --annotationdescriptiondescription of the alert \ --generator-urlhttp://prometheus.example.com/graph \ --start2026-09-15T06:00:00Z \ --end2026-09-15T07:00:00Z各参数说明与源码configureAddAlertCmd一一对应labels位置参数keyvalue形式的标签列表--generator-url设置generatorURL字段--start/--end设置startsAt/endsAt源码中使用time.Parse(time.RFC3339, ...)解析必须为 RFC3339 格式--annotation可重复使用设置annotations字段。在源码中非keyvalue形式的裸参数会被自动改写为alertnamevalue见 cli/alert_add.go 中compat.Matcher的容错逻辑且标签与注解均要求等值匹配MatchEqual否则返回错误。五、配套只读接口查询告警与状态除写入外APIv2 还提供完整的只读接口方便验证发送结果GET /api/v2/alerts查询告警列表支持active、silenced、inhibited、unprocessed四个布尔过滤参数默认均为true以及可重复的filter匹配表达式如alertnameMyAlert和receiver按接收器正则过滤查询参数GET /api/v2/alerts/groups按分组查询告警额外支持muted参数返回每个告警组及其receiver信息GET /api/v2/status查看实例状态、集群信息与当前生效配置原文GET /api/v2/receivers列出所有接收器GET /api/v2/silences/POST /api/v2/silences/DELETE /api/v2/silence/{silenceID}静默的管理。返回的gettableAlert相比写入时的postableAlert额外包含receivers接收器引用、fingerprint去重指纹、updatedAt与status状态为unprocessed/active/suppressed并附silencedBy、inhibitedBy、mutedBy列表这些字段均可在 api/v2/openapi.yaml 的definitions一节中查到完整定义。六、小结Alerts API 的使用要点可概括为三句话数据上向POST api/v2/alerts发送带Content-Type: application/json的告警数组labels必填、时间戳用 RFC3339语义上省略startsAt取当前时间、省略endsAt取当前时间加resolve_timeout且重发会续期endsAt契约上客户端需持续重发 firing 告警并在解决后继续重发最多 5 分钟以弥补 Alertmanager 无状态重启带来的通知丢失风险。理解并遵守这套约定是将任何自定义监控系统稳定接入 Alertmanager 通知链路的前提。【免费下载链接】alertmanagerPrometheus Alertmanager项目地址: https://gitcode.com/GitHub_Trending/al/alertmanager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
