Prometheus 标签(Label)有哪些限制?

Prometheus 标签的限制包括:legacy 标签名匹配 [a-zA-Z_][a-zA-Z0-9_]*,Prometheus 3 支持 UTF-8 名称;抓取可配置数量及字节长度限制、双下划线前缀保留、组合基数决定性能上限。本文列出全部硬性限制与避免高基数事故的实践。

最佳实践
Prometheus 标签(Label)有哪些限制?封面

传统名称模式的标签名匹配 [a-zA-Z_][a-zA-Z0-9_]*;Prometheus 3 支持 UTF-8 名称,但客户端/协议/查询兼容仍需核对,双下划线前缀(__)保留给内部使用;真正的"软限制"是基数——标签组合总数决定 Prometheus 的内存与查询性能。

硬性规则

  1. 标签名:字母/下划线开头,只含字母、数字、下划线;这是 legacy 名称规则;UTF-8 模式下可接受更广字符,PromQL 中需按语法引用,采集端也须支持;
  2. 保留前缀:__ 前缀保留;目标 relabel 阶段的内部标签(如 __address__)在该阶段结束后移除,不能据此认为指标名使用的 __name__ 也会被一律丢弃;
  3. 传统指标名规则允许额外的冒号,冒号通常保留给录制规则;不完全同标签名;
  4. 标签值:UTF-8 字符串;抓取配置可设 label_value_length_limit 等限制(按字节),还可限制标签数量/名称长度——但值越长存储越大。

真正的瓶颈:基数

每条"指标名 + 全部标签组合"是一个独立时序。标签取值越多,序列数爆炸式增长:

100 实例 × 50 接口 × 10 状态码 = 5 万条序列(一个指标!)

容量目标须基于真实资源、保留和查询测量,以下不是通用安全线:单实例活跃序列(prometheus_tsdb_head_series)控制在数百万级以内;单指标的标签组合最好控制在千级。

实践建议

  • 标签只放"会用来分组/过滤"的维度;
  • 用户 ID、请求 ID、时间戳、完整 URL 路径——永远不做标签(放日志或链路里);
  • 不确定时先上线观察序列增速,再放量。

常见问题(FAQ)

Q:标签名大小写敏感吗? 敏感。Method 和 method 是两个标签。

Q:标签数量有上限吗? 可由 label_limit 等抓取配置限制;每个标签有开销,10个以内只是经验而非协议保证。

Q:如何发现高基数指标? 查 topk(10, count by (__name__) ({__name__=~".+"})) 取前几名审查。

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台