标注（Annotation）

标注是什么

Annotation 是叠加在时间轴图表上的垂直线或图标，代表「某个时刻发生过什么」：部署、配置变更、告警触发。指标异动配上事件线，是复盘与值班交接时最有用的上下文。

三种来源

1. 内置标注：Grafana 自己记录的事件，如仪表盘变更、告警状态变化，开箱即用。
2. 数据源标注：从 Prometheus、Loki、PostgreSQL 等数据源里查出来的事件。
3. JSON 手写标注：直接写进仪表盘模型的静态事件列表。

内置标注

面板进入编辑模式后，图表上方有 Add annotation（或标注图标）入口，选择内置的 Grafana annotation 即可显示告警状态变化等事件；不同版本的菜单名称略有差异，以实际界面为准。告警类标注最实用： firing 与 resolved 的时刻直接钉在曲线上。

数据源标注

若事件已经以指标形式进了 Prometheus（例如告警组 ALERTS），可以建一条查询标注：

ALERTS{alertname="HighErrorRate", alertstate="firing"}

添加步骤：

1. 面板编辑模式点图表上方 Add annotation，选 Annotations query（部分版本在 Dashboard settings → Annotations 提供同名入口）。
2. 选择数据源与查询语句，按需配置 Tags 字段（Loki 则用标签）。
3. 保存后事件以竖线出现，悬停可看详情。

各数据源对字段有约定：SQL 类一般映射 time、title、text、tags 列；Loki 需要日志行携带 title、text、labels 字段。

提示： 标注查询同样支持变量，{service="$service"} 让标注跟随下拉框联动。

JSON 手写标注

适合固定事件（大促、割接窗口），写进仪表盘 JSON 模型的 annotations 键：

{
  "annotations": {
    "list": [
      {
        "name": "Grafana 内置",
        "builtIn": 1,
        "enable": true,
        "hide": false
      },
      {
        "name": "手动事件",
        "datasource": { "type": "grafana", "uid": "-- Grafana --" },
        "enable": true,
        "iconColor": "blue",
        "type": "event"
      }
    ]
  }
}

注意： builtIn: 1 那一项是内置标注开关，删掉后「Alerts」等内置事件线会一并消失。

在图上显示与隐藏

• 图表上方的标注图标列出当前所有标注源，逐条 Enable / Hide 控制显隐。
• 全局管理入口在仪表盘设置或编辑模式的 Annotations 面板（名称随版本变化）。
• 嵌入与 kiosk 模式下显隐状态跟随仪表盘保存的配置，想要稳定行为就把它写进 JSON。

常见坑

• 标注不出现：检查事件时间是否落在当前时间窗口内，以及标注源是否被 Hide。
• 竖线密集遮挡：数据源标注查询过宽会把图变成斑马线，收紧标签或加阈值条件。
• 导出 JSON 后标注丢数据源：标注也带 datasource.uid，跨实例导入时要重新绑定。

下一步

• 产生标注事件的规则本身，见告警规则。
• 用日志复盘事件前后，见探索日志。
• 标注查询用到的标签过滤，见模板变量。