Jira¶
Jira 通知对象通过 Webhook(接收外部通知的 HTTP 入口),将观测云告警以 JSON 格式发送到 Jira 接收流程。您可以在 Jira 中配置字段映射和处理动作,将告警交给项目团队处理。
本文以 Jira Cloud Automation 的 Incoming webhook 为例。工单所属项目、类型、创建或更新规则、去重及状态维护均由 Jira 自动化规则控制。
在 Jira 配置接收规则¶
需要拥有目标项目自动化规则的编辑权限。
- 进入目标 Jira 项目的 Automation,新建自动化规则。
- 添加 Incoming webhook 触发器。
- 添加 Create issue 等处理动作,选择项目和工单类型。首次联通测试可先使用固定摘要,例如“监控通知测试”;确认接收后,再按实际告警将摘要映射为
{{webhookData.title}},描述映射为{{webhookData.message}}。 - 选择 Save flow without enabling,填写规则名称并保存。
- 重新打开 Incoming webhook 触发器,选择 No issues from the webhook,复制 Webhook URL 和 Secret;保存触发器配置并启用规则。
Jira 使用 webhookData 读取请求中的 JSON 字段。一次告警通知可包含多个事件,请根据业务需要,按整条通知建单,或遍历 events 分别处理事件,并将事件上下文、回链及 monitor_checker_links 中的监控器链接映射到工单字段。
接收入口与 Secret 的配置参见 Jira Incoming webhook 官方文档;字段映射参见 Jira 官方告警接入示例。
在观测云新建通知对象¶
进入监控 > 通知对象管理 > 新建通知对象,选择 Jira。
- 输入名称,用于在列表和告警策略中识别通知对象。名称在当前工作空间内唯一,最多 200 字。
- 在 Webhook 地址中填入 Jira 提供的完整 HTTPS URL,使用实际接收 POST 请求的最终地址。
- 认证方式选择 Secret,填入 Jira 生成的 Secret。系统通过
X-Automation-Webhook-Token请求头发送该值。 - 按接收端要求设置其他认证方式和自定义请求头。
- 点击测试通知发送,预览并确认发送。测试会实际调用 Jira 规则,后续动作按规则执行。
- 前往 Jira 的 Audit log,确认出现本次规则执行记录,并核对告警字段和工单处理结果。
- 配置操作权限,确认保存。
- 在告警策略中选择该通知对象,配置需要发送的事件等级和范围。
其他认证方式与自定义请求头¶
Jira Cloud Automation 原生 Incoming webhook 使用 Secret。接入网关、插件或自建接收服务时,按该入口实际支持的协议选择认证方式。
| 认证方式 | 填写内容 | 使用说明 |
|---|---|---|
| Secret | Secret | 适用于上述 Jira Cloud Automation 入口。 |
| Basic | 用户名、密码 | 按接收端约定提供凭据,用户名保持非空且不含冒号。 |
| Bearer Token | Token | 填写已有 Access Token 的原值,系统添加 Bearer 前缀;请在令牌到期或撤销后更新。 |
| API Key | 请求头名称、API Key | 按接收端约定填写请求头名称和完整值;Content-Type 为保留名称。 |
| 无认证 | — | 按接收端要求设置自定义请求头。 |
按需开启自定义请求头,添加接收端要求的键和值。头名称按大小写无关去重;所选认证方式生成的请求头优先于同名自定义头。Content-Type 固定为 application/json,Accept 默认为 application/json。
编辑凭据¶
编辑已保存对象时,同一地址、认证方式及身份下,Secret、密码、Token 或 API Key 留空可保留原值,输入新值可替换。更换地址、认证方式、用户名或 API Key 请求头名称后,需要填写对应凭据。
自定义请求头值加密保存。在上述配置保持一致时,已保存的同名请求头值留空可保留,输入新值可替换;删除行会移除该头。新增或重命名请求头,以及更换上述配置后,请填写完整的请求头值。
测试使用当前表单中的有效配置;保存后,后续告警使用新配置。重新生成 Jira Secret 后,请同步更新通知对象中的 Secret。
通知内容与告警聚合¶
Jira 通知对象沿用简单 HTTP 请求的告警聚合形式,支持普通、规则聚合和智能聚合通知。接收端按以下字段解析告警:
| 字段 | 含义 |
|---|---|
title、message、status |
当前通知的标题、正文和状态。 |
events |
事件列表。普通告警包含一个事件;聚合告警包含对应的一组事件,保留事件上下文和回链。 |
workspace_uuid、workspace_name |
事件所属工作空间的 ID 和名称。 |
monitor_checker_links |
规则聚合和智能聚合通知中的监控器名称与事件列表链接。 |
告警策略决定哪些事件组成同一条通知;通知内容构造完成后启动发送。配置了显式延迟的通知仍按指定时间发送。
测试与排查¶
测试通知的字段以接收端实际收到的 JSON 为准。完成入口和认证测试后,再用实际普通、聚合告警验证 title、events 等字段的映射;首次测试使用固定摘要可避免测试样例缺少 title 时建单失败。
接收入口返回 HTTP 2xx,仅表示请求完成。Jira 新版 Incoming webhook 在 Secret 错误或规则不存在时,也可能返回 HTTP 200。请以 Audit log 中的本次执行记录、字段解析和后续动作结果判断接入是否成功。
| 现象 | 检查方式 |
|---|---|
| 请求完成,Audit log 中没有本次记录 | 检查规则已启用、URL 与 Secret 来自同一触发器;重新生成 Secret 后同步更新通知对象。 |
| 规则执行,工单字段为空 | 检查 webhookData 字段路径,并用实际普通、聚合告警分别验证解析。 |
| 工单数量与预期不同 | 检查规则按整条通知还是按 events 中的事件执行,以及 Jira 侧的去重规则。 |
| 发送失败 | 检查最终 HTTPS 地址、证书、网络连通性和接收端权限。HTTP 3xx 重定向按发送失败处理。 |
更多排查方法参见 Jira Incoming webhook 官方测试指南。