Prometheus 本身不支持在指标中直接嵌入任意文本注释（如 # COMMENT），但可通过标签（labels）将元数据（如 OS 版本、内核版本）作为维度附加到指标上，实现语义化、可查询的“动态注释”效果。
prometheus 本身不支持在指标中直接嵌入任意文本注释（如 `# comment`），但可通过标签（labels）将元数据（如 os 版本、内核版本）作为维度附加到指标上，实现语义化、可查询的“动态注释”效果。
在 Prometheus 生态中，指标的元信息（如 HELP、TYPE）是静态的、全局的，仅用于文档说明；而实际运行时的动态上下文（例如当前实例的 os_version="Ubuntu 22.04.3 LTS" 或 kernel_version="6.5.0-41-generic"）必须通过标签（labels）表达——这是 Prometheus 的核心设计原则：所有维度化信息都应建模为键值对标签，而非文本注释。
✅ 正确做法：用标签承载元数据
以 Gauge 类型为例，您不应尝试在指标行上方插入 # COMMENT，而应将版本信息作为标签注入：
// 使用 prometheus/client_golang 示例
var (
osVersionGauge = prometheus.NewGaugeVec(
prometheus.GaugeOpts{
Name: "service_os_version",
Help: "OS version of the service instance (encoded as label, value is always 1 for presence)",
},
[]string{"os", "version", "arch"}, // 标签维度
)
)
func init() {
prometheus.MustRegister(osVersionGauge)
}
func recordOSInfo() {
osVersionGauge.WithLabelValues("ubuntu", "22.04.3 LTS", "amd64").Set(1)
}
暴露后，该指标在 /metrics 端点中呈现为：
# HELP service_os_version OS version of the service instance (encoded as label, value is always 1 for presence)
# TYPE service_os_version gauge
service_os_version{os="ubuntu",version="22.04.3 LTS",arch="amd64"} 1
此时，您即可在 Prometheus 查询中灵活筛选与聚合：
-
service_os_version{os="ubuntu"}→ 查看所有 Ubuntu 实例 -
count by (version) (service_os_version)→ 统计各 OS 版本分布 - 与其他业务指标（如
http_requests_total）通过相同标签（如instance,job）进行join或group_left关联分析
⚠️ 注意事项与最佳实践
-
标签值必须为字符串，且不可含空格/特殊字符（推荐 URL-safe 编码）：如
version="22.04.3%20LTS"，避免解析错误。 -
避免高基数标签：
ip_addr或随机 ID 类标签易导致存储与查询性能下降；OS/Kernel 版本属于低基数（通常 -
不要滥用
0值指标：虽然可用kernel_version{version="6.5.0"} 0表达存在性，但语义不如service_kernel_info{version="6.5.0"} 1清晰；建议统一使用1表示“该元数据存在”。 -
静态元数据也可通过 Service Discovery 注入：若使用 Prometheus Operator 或 Consul SD，可将
os_version作为 target label 在发现阶段注入，无需修改应用代码。
✅ 总结
Prometheus 没有 # COMMENT 语法，但其标签模型比静态注释更强大：它让元数据可查询、可聚合、可关联、可告警。将 OS、内核、部署环境等信息作为标签注入指标，不是妥协，而是遵循可观测性最佳实践——让每一行指标自带上下文，真正实现“自描述监控”。
