自定义Prometheus Exporter中Describe接口的作用及使用时机咨询

我当初在实现动态指标的Prometheus Exporter时，也纠结过Describe和Collect的分工问题，刚好可以给你拆解清楚：

一、Describe接口的核心作用 #

简单来说，Describe是用来提前暴露指标的元数据信息，它的价值主要体现在这几点：

1. 提升采集效率：Prometheus（或其他监控系统）会提前缓存Describe返回的指标描述符（Desc对象），不用每次调用Collect时都重新解析指标的名称、类型、帮助文本等信息，减少重复计算。
2. 规范指标一致性：确保所有可能出现的指标都有统一的元数据定义，避免Collect中动态生成的指标出现拼写错误、类型不一致等问题——如果Describe返回的描述符和Collect中生成的不匹配，Prometheus会抛出错误，帮你提前发现问题。
3. 兼容元数据采集场景：有些监控系统或工具依赖提前获取指标列表（比如自动生成监控面板、做指标权限控制），Describe就是给这些场景提供数据源的。

二、Describe的使用时机 #

• 当你的Exporter有固定指标（比如exporter_up、scrape_duration_seconds这类基础指标）时，必须在Describe中返回它们的Desc对象——这些指标是每次采集都会存在的，提前暴露完全没问题。
• 当你的Exporter有可预测的动态指标（比如根据配置文件生成的指标、固定前缀的自定义指标）时，建议在Describe中预先生成并返回对应的Desc对象，这样能充分利用Prometheus的缓存机制。
• 当你的Exporter有完全不可预测的动态指标（比如根据实时数据库数据、用户请求动态生成的指标）时，不用强行在Describe中返回所有可能的Desc——这时候可以只返回固定指标的Desc，剩下的动态指标的Desc在Collect中生成即可。

三、动态指标场景的具体实现示例 #

假设你需要根据实时业务数据动态生成指标，这里给你一个符合规范的实现思路：

type DynamicCollector struct {
    // 固定指标的描述符，提前初始化
    upDesc *prometheus.Desc
}

func NewDynamicCollector() *DynamicCollector {
    return &DynamicCollector{
        upDesc: prometheus.NewDesc(
            "my_exporter_up",
            "Whether the exporter is running",
            nil,
            nil,
        ),
    }
}

// Describe：只返回固定指标的描述符
func (c *DynamicCollector) Describe(ch chan<- *prometheus.Desc) {
    ch <- c.upDesc
    // 动态指标的描述符不用在这里返回，因为没法提前知道
}

// Collect：动态生成指标及其描述符
func (c *DynamicCollector) Collect(ch chan<- prometheus.Metric) {
    // 先上报固定指标
    ch <- prometheus.MustNewConstMetric(c.upDesc, prometheus.GaugeValue, 1)

    // 模拟从业务系统获取动态数据
    dynamicMetrics := map[string]float64{
        "user_login_success": 1234,
        "order_created": 567,
    }

    // 动态生成每个指标的描述符和指标值
    for metricName, value := range dynamicMetrics {
        // 动态创建描述符
        desc := prometheus.NewDesc(
            fmt.Sprintf("my_exporter_%s", metricName),
            fmt.Sprintf("Dynamic metric for %s", metricName),
            nil,
            nil,
        )
        // 生成指标并上报
        ch <- prometheus.MustNewConstMetric(desc, prometheus.CounterValue, value)
    }
}

这里要注意：虽然动态指标的Desc没在Describe中返回，但Prometheus依然能正常采集到这些指标——只是第一次采集时需要解析这些Desc，后续会自动缓存。如果你的动态指标数量特别多，可能会影响第一次采集的性能，但大部分场景下这个影响可以忽略。

四、避坑提醒 #

• 不要在Describe中做耗时操作（比如请求数据库、调用外部接口）——Describe会在Collector注册时被调用，耗时操作会拖慢Exporter的启动速度。
• 确保同一个指标的Desc在Describe和Collect中是完全一致的（包括名称、标签、帮助文本），否则Prometheus会抛出"duplicate descriptor"的错误。
• 如果动态指标的标签是动态的，建议在Describe中返回带有标签占位符的Desc，比如prometheus.NewDesc("my_exporter_metric", "...", []string{"label_name"}, nil)，这样Prometheus可以提前知道标签结构。

内容的提问来源于stack exchange，提问作者gavenant