prometheus 不支持在指标中直接添加任意文本注释，但可通过标签（labels）将 os 版本、内核版本等元信息作为维度嵌入指标，既保持标准格式，又实现自描述与灵活查询。
prometheus 不支持在指标中直接添加任意文本注释，但可通过标签（labels）将 os 版本、内核版本等元信息作为维度嵌入指标，既保持标准格式，又实现自描述与灵活查询。
在 Prometheus 生态中，# HELP 和 # TYPE 是唯一的标准化注释机制，用于描述指标语义和类型，不支持动态、实例级的文本注释（如 `OS version is xxxx`）。若需携带运行时环境信息（如 os_version="Ubuntu 22.04", kernel_version="6.5.0-41-generic"），正确且符合最佳实践的方式是：将这些信息建模为指标标签（Labels），而非尝试注入非标准注释行。
✅ 推荐方案：使用标签（Labels）承载元数据
所有 Prometheus 客户端库（Go、Python、Java 等）均原生支持为指标添加标签。以 Gauge 为例：
// Go 示例：使用 prometheus/client_golang
var (
serviceInfo = prometheus.NewGaugeVec(
prometheus.GaugeOpts{
Name: "service_info",
Help: "Static info about the service (always 1, used for label-based discovery)",
},
[]string{"os_version", "kernel_version", "arch", "hostname"},
)
)
func init() {
prometheus.MustRegister(serviceInfo)
}
func recordSystemInfo() {
serviceInfo.With(prometheus.Labels{
"os_version": "Ubuntu 22.04.4 LTS",
"kernel_version": "6.5.0-41-generic",
"arch": "amd64",
"hostname": "web-prod-01",
}).Set(1) // 值固定为 1，仅作元数据载体
}
暴露后，该指标在 /metrics 中呈现为：
# HELP service_info Static info about the service (always 1, used for label-based discovery)
# TYPE service_info gauge
service_info{os_version="Ubuntu 22.04.4 LTS",kernel_version="6.5.0-41-generic",arch="amd64",hostname="web-prod-01"} 1
✅ 优势显著：
-
可查询：
service_info{os_version=~"Ubuntu.*"}或count by (os_version)(service_info) -
可聚合：
count by (kernel_version)(service_info)统计各内核版本实例数 -
零侵入：不影响原有业务指标结构，与
http_request_duration_seconds等正交共存 - 符合规范：完全兼容 Prometheus 数据模型与远程存储
⚠️ 注意事项与避坑指南
- ❌ 不要伪造
# HELP行：例如在/metrics响应中动态插入# HELP os_version Kernel version of host—— 这违反 Prometheus 文本格式规范，会导致抓取失败或解析错误。 - ❌ 避免用指标值存储字符串：Prometheus 值必须为浮点数，无法直接存
"5.15.0-76-generic"；强行转为数字（如哈希）会丧失可读性与语义。 - ✅ 静态元数据优先用
service_info类指标：值设为1，纯作标签容器，语义清晰、开销极低。 - ✅ 动态变更场景慎用高基数标签：如
request_id或user_email作为标签会导致严重性能问题；而os_version属于低基数（通常
? 替代思路（不推荐，仅作了解）
若坚持“注释感”，可导出一个无实际度量意义的 info 指标（社区常见模式）：
# HELP node_uname_info Info about the uname system call
# TYPE node_uname_info gauge
node_uname_info{sysname="Linux", release="6.5.0-41-generic", version="#41~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Thu Jun 27 20:15:30 UTC 2", machine="x86_64"} 1
这是 Node Exporter 的标准做法 —— 将系统信息映射为带丰富标签的 gauge，值恒为 1，本质仍是标签驱动。
总之，标签即文档，维度即语义。拥抱 Prometheus 的数据模型，用 Label 承载上下文，远比绕过规范“硬塞注释”更健壮、可扩展、易运维。
