配置可观测监控Prometheus

背景

推荐链路包含诸多环节，除了引擎整体的运行情况，通常还需要更细致的数据来观测各个环节。

PAI-Rec 引擎支持通过 Prometheus 来采集指标数据，可以实现以下几点目标：

1. 增强系统可见性：通过收集和分析多维度的指标数据，帮助开发和运维团队更清晰地了解系统的运行状况和性能瓶颈。

2. 快速故障排查：可观测性使团队能够快速识别和定位系统中的问题来源，缩短故障解决时间，从而提高系统的可靠性和可用性。

3. 提高响应效率：通过实时监控和预警机制，团队可以在问题影响到用户之前采取措施，从而减少因系统故障导致的损失。

开启指标采集

指标采集功能通过在引擎配置单中增加对应配置来开启，配置示例如下：

{
  "PrometheusConfig": {
    "Enable": true,
    "PushGatewayURL": "https://your_pushgateway_url",
    "PushIntervalSecs": 15
  }
}

配置说明：

两种采集方式

PAI-Rec 引擎支持 Pull 和 Push 两种指标采集方式：

Pull 方式下，引擎暴露以下两个接口，分别对应内置指标和自定义指标：

• 内置指标：http://${your_service_host}/metrics

• 自定义指标：http://${your_service_host}/custom_metrics

重要：引擎服务部署在 PAI-EAS 时，实例动态调度且经由网关访问，Pull 方式无法正确获取所有实例的指标，请使用 Push 方式。

观测指标

以下用接入阿里云可观测监控 Prometheus 版（云监控）为例，说明如何观测指标。

资源准备

• 已开通云监控可观测监控 Prometheus 版。

• 已创建 Prometheus 实例：控制台侧边栏 Prometheus 监控 > 实例列表 > 新建 Prometheus 实例。

• 已将 Prometheus 实例集成到一个非共享 Grafana 工作区，如当前地域还没有非共享的 Grafana 工作区则需要新建：控制台侧边栏 Grafana 服务 > 工作区管理 > 云服务集成，选择 Prometheus 实例，单击集成。

接入步骤

1. 获取 Push Gateway 地址：在云监控的控制台的实例列表中，单击目标实例右侧操作列的设置，在 Push Gateway 地址区域获取 URL。请根据引擎服务的实际网络环境选择公网或内网地址。

2. 配置鉴权：根据实例版本完成鉴权配置，具体请参见下文「云监控 Push Gateway 鉴权」。以 V2 版实例为例，需为 RAM 角色 AliyunPAIRecEASRole 授予 AliyunPrometheusMetricWriteAccess 权限。

3. 开启引擎指标推送：在引擎配置单中增加 PrometheusConfig 配置并重启引擎。

4. 验证指标推送：检查引擎服务日志，确认无 Error sending to push gateway 报错；也可在 Prometheus 监控实例的指标管理页面查询内置指标（如 pairec_rec_total）确认有数据。

5. 导入指标面板：访问 Grafana 公网（或私网）地址并登录，单击侧边栏仪表板（Dashboard），单击右上角新建，选择导入，上传面板配置 JSON 文件（下载链接：PAI-Rec Grafana 面板配置 JSON），设置 datasource 为对应的 Prometheus 实例，单击导入。

完成上面的步骤就可以看到指标面板了。除了已经配置好的指标面板，也可以参考下文指标说明，自行添加面板进行观测。

云监控 Push Gateway 鉴权

云监控 Prometheus 实例的 Push Gateway 默认不允许匿名写入，未通过鉴权的推送请求会返回 401 错误。请根据实例版本和免密配置情况，选择对应的接入方式：

免密访问

在 Prometheus 实例上开启写入免密并配置客户端 IP 白名单后，白名单内的客户端推送数据时无需携带鉴权信息，引擎侧无需额外配置。具体操作，请参见配置并使用Prometheus V2实例的免密访问功能。

重要：开启免密访问后，请勿在引擎配置中填写 PushGatewayToken 或开启 PushGatewayUseAliyunCredential，否则服务端仍按携带的身份进行 RAM 鉴权，可能导致访问被拒绝。

Token 鉴权（云监控 V1 版实例）

V1 版实例的 Push Gateway 数据保护基于控制台生成的 Token 实现，开启 Token 保护后需在引擎配置中携带 Token。

1. 登录云监控的控制台，进入目标实例的设置页面，在 Token 区域单击生成 token，复制 Token 值。

2. 在引擎配置中填写 PushGatewayToken，并重启引擎。

{
  "PrometheusConfig": {
    "Enable": true,
    "PushGatewayURL": "https://your_pushgateway_url",
    "PushIntervalSecs": 15,
    "PushGatewayToken": "your_token"
  }
}

阿里云凭证鉴权（云监控 V2 版实例）

V2 版实例基于阿里云 RAM 体系鉴权，不支持 Token 方式。开启 PushGatewayUseAliyunCredential 后，引擎通过阿里云默认凭证链自动获取凭证完成鉴权，支持 STS 临时凭证自动刷新。引擎部署在 PAI-EAS 时，将自动使用 EAS 实例关联的 RAM 角色（AliyunPAIRecEASRole）获取临时凭证，无需配置明文 AccessKey。

1. 为 RAM 角色授予指标写入权限。

   1. 使用阿里云主账号或 RAM 管理员登录 RAM 控制台，在左侧导航栏选择权限管理 > 授权。

   2. 在授权页面，单击新增授权，并进行如下配置。

      参数	说明
      资源范围	按需选择资源范围。
      授权主体	选择 RAM 角色 AliyunPAIRecEASRole。
      权限策略	选中 AliyunPrometheusMetricWriteAccess 或 AliyunCloudMonitorFullAccess。

   3. 单击确认新增授权，单击关闭。

2. 在引擎配置中开启 PushGatewayUseAliyunCredential，并重启引擎。

{
  "PrometheusConfig": {
    "Enable": true,
    "PushGatewayURL": "https://your_pushgateway_url",
    "PushIntervalSecs": 15,
    "PushGatewayUseAliyunCredential": true
  }
}

指标面板

系统概览

• 接口请求量展示接口每秒请求数，即QPS，并按状态码，接口uri两个维度展示

• 接口响应时间展示接口 T99, T95, T90 响应时间，反映接口响应速度

• 内存占用反映了 PAI-Rec 引擎实例占用的内存随时间的变化，每个实例对应一条曲线

• GO 协程反映了 PAI-Rec 引擎实例协程数量随时间的变化，每个实例对应一条曲线

• 推荐数量不足错误展示 引擎无法返回足够的推荐条目的错误数量

召回指标

• 召回数量占比反映各个召回通道获取的推荐条目在总的推荐条目中的占比

• 召回耗时反映召回速度快慢，和接口请求响应时间一样，分别展示了 T99, T95, T90 数据

过滤指标

• 过滤耗时反映过滤速度快慢，和接口请求响应时间一样，分别展示了 T99, T95, T90 数据

粗排指标

• 粗排耗时反映粗排速度快慢，和接口请求响应时间一样，分别展示了 T99, T95, T90 数据

精排指标

• 精排耗时反映精排速度快慢，和接口请求响应时间一样，分别展示了 T99, T95, T90 数据

重排指标

• 重排耗时反映重排速度快慢，和接口请求响应时间一样，分别展示了 T99, T95, T90 数据

常见问题

1. Prometheus 无法接收到指标

请检查引擎服务日志，查看是否有 Error sending to push gateway 或 Error push gateway 报错，根据报错情况分别处理：

• 报错提示 response code 为 401：鉴权失败。请根据实例版本和免密配置情况，参照上文「云监控 Push Gateway 鉴权」检查对应配置：

  • V1 版实例：确认已在引擎配置中填写 PushGatewayToken，且 Token 与控制台生成的一致。

  • V2 版实例：确认已开启 PushGatewayUseAliyunCredential，且已为 RAM 角色 AliyunPAIRecEASRole 授予 AliyunPrometheusMetricWriteAccess 权限。

  • 已开启免密访问的实例：确认客户端 IP 在免密白名单内，且引擎配置中未填写任何鉴权字段（携带鉴权信息时服务端仍按该身份进行 RAM 鉴权）。

• 报错提示超时：目前上报指标的连接超时限制为 10 秒。请检查引擎服务和 Prometheus 之间网络是否正常，以及配置中填写的 Push Gateway 地址是否正确（注意区分公网、内网地址）。

• 没有报错：请确认更新引擎配置后是否已重启引擎服务。

2. Grafana 面板部分指标无数据

请检查面板左上角筛选设置：环境筛选下拉框标记为 env，场景筛选下拉框标记为 scene，需确认其分别选中了正确的环境（如 prepub）和场景（如 home_feed）。

3. 接口耗时指标不准确

接口耗时的 T99、T95 等分位数是基于 Histogram 分桶（bucket）估算的，实际值只能落在某个桶区间内。如果分桶设置与实际耗时分布不匹配，例如大部分请求耗时集中落在同一个桶内，或超出最大桶边界，估算出的分位数会明显失真（超出最大桶边界时，分位数恒等于最大桶边界值）。

接口耗时指标默认使用 Prometheus 标准分桶（0.005 秒 ~ 10 秒），桶间隔较稀疏。可通过 ReqDurBuckets 配置自定义分桶，让分桶在实际耗时集中的区间内更加密集。例如接口耗时集中在 20 毫秒 ~ 500 毫秒时，可参考如下配置：

{
  "PrometheusConfig": {
    "Enable": true,
    "ReqDurBuckets": [0.01, 0.02, 0.03, 0.05, 0.08, 0.1, 0.15, 0.2, 0.3, 0.5, 1, 2.5]
  }
}

说明：

• 分桶单位为秒，需按从小到大排列。

• 建议分桶范围覆盖实际耗时的最小值到最大值，并在分位数关注区间（如 T99 附近）加密分桶；桶数量适度即可，过多会增加指标存储开销。

• 修改配置后请重启引擎，使配置生效。

内置指标说明

以上类型为 Histogram 的指标会反映当前指标的记录的总数（以_count作为后缀）以及其值的总量（以_sum作为后缀）和分布区间（以_bucket作为后缀）。

除了这些指标，PAI-Rec 也采集了 Go 进程本身的指标数据。

指标数据还会带有 instance 和 job 信息，instance 表示来自哪个实例，job 表示来自哪个环境（生产环境为 product， 预发环境为 prepub）

自定义指标

如果需要获取和推送自定义指标，那么需要在 pairec 引擎代码中注册自定义指标，示例代码如下：

package main
import (
	"log"
	"time"
	"github.com/alibaba/pairec/v2"
	"github.com/alibaba/pairec/v2/service/metrics"
	"github.com/prometheus/client_golang/prometheus"
)
func main() {
        // 定义指标
	m := prometheus.NewCounter(prometheus.CounterOpts{
		Name: "abc",
	})
        // 在 pairec 中注册指标
	err := metrics.CustomRegister.Register(m)
	if err != nil {
		log.Fatalln(err)
	}
	go func() {
		for {
			time.Sleep(time.Second * 5)
			m.Inc() // 采集指标数据
		}
	}()
	// ...
	pairec.Run()
}

在 CustomRegister 注册自定义指标后，就能从 /custom_metrics 接口获取到自定义指标的数据了。

如果开启了推送配置，自定义指标数据也会被推送到 prometheus gateway。

示例代码中简单起见只是开启了一个协程定时设置指标数据，实际情况中可以在接口 controller 逻辑中或任意其他位置设置指标数据。