Prometheus 本身不支持在指标中直接嵌入自由文本注释（如 # OS version is xxxx），但可通过标签（Labels）将元数据（如 OS、内核版本）作为维度附加到指标上，实现语义化、可查询的动态注释效果。
prometheus 本身不支持在指标中直接嵌入自由文本注释（如 `# os version is xxxx`），但可通过标签（labels）将元数据（如 os、内核版本）作为维度附加到指标上，实现语义化、可查询的动态注释效果。
在 Prometheus 生态中，指标的“注释”并非以传统注释（comment）形式存在——它不支持 # OS version is xxxx 这类非标准行写入指标暴露端点（如 /metrics）。这是因为 Prometheus 的文本格式规范（Metrics exposition format）仅允许 # HELP、# TYPE 和 # UNIT 行作为元数据，且其内容必须是静态、全局一致的说明，不可动态变化。
✅ 正确做法：使用 标签（Labels） 承载动态环境信息
标签是 Prometheus 的核心设计特性，用于对同一指标进行多维切片。你可以将 os_version、kernel_version、hostname 等作为标签键，随指标一同上报：
# 示例：带环境维度的 gauge 指标（通过 client_golang 实现）
http_request_duration_seconds{job="api-server", instance="10.0.1.23:8080", os_version="Ubuntu 22.04.4", kernel_version="6.5.0-41-generic"} 0.142
这样，你既能保留指标语义（如请求时长），又能通过 PromQL 精准筛选或聚合特定系统版本的数据：
# 查询所有 Ubuntu 22.04 主机的平均请求延迟
avg(http_request_duration_seconds{os_version=~"Ubuntu 22.04.*"}) by (instance)
# 按内核版本分组统计指标数量
count(http_request_duration_seconds) by (kernel_version)
? 实现方式（以 Go 客户端为例）
使用 prometheus/client_golang 时，需定义带标签的 GaugeVec，并在采集时动态注入值：
import "github.com/prometheus/client_golang/prometheus"
// 定义带 os_version 和 kernel_version 标签的 Gauge
httpDuration := prometheus.NewGaugeVec(
prometheus.GaugeOpts{
Name: "http_request_duration_seconds",
Help: "A histogram of the request duration.",
},
[]string{"instance", "os_version", "kernel_version"},
)
// 注册并初始化
prometheus.MustRegister(httpDuration)
// 采集时动态设置标签值（例如从 runtime 获取）
httpDuration.WithLabelValues(
"10.0.1.23:8080",
"Ubuntu 22.04.4",
"6.5.0-41-generic",
).Set(0.142)
⚠️ 注意事项：
- 标签值应尽量保持低基数（cardinality）：避免将高变字段（如请求 ID、用户邮箱）作为标签，否则易引发内存爆炸与性能下降；
- 不要滥用
# HELP/# TYPE行做动态描述——它们仅用于文档目的，且在 scrape 时被忽略其值变化； - 若需纯元数据（无数值意义），可导出一个恒为
0的gauge指标（如system_info{os_version="..."}），但需确保其用途明确、不参与计算逻辑。
? 总结：Prometheus 的“注释”本质是结构化维度。将版本、环境等信息转化为标签，不仅符合其数据模型，更能释放 PromQL 强大的多维分析能力——这才是真正可监控、可告警、可追溯的动态注释。
