Prometheus 标签(Label)有哪些限制?
Prometheus 标签的限制包括:legacy 标签名匹配 [a-zA-Z_][a-zA-Z0-9_]*,Prometheus 3 支持 UTF-8 名称;抓取可配置数量及字节长度限制、双下划线前缀保留、组合基数决定性能上限。本文列出全部硬性限制与避免高基数事故的实践。
传统名称模式的标签名匹配 [a-zA-Z_][a-zA-Z0-9_]*;Prometheus 3 支持 UTF-8 名称,但客户端/协议/查询兼容仍需核对,双下划线前缀(__)保留给内部使用;真正的"软限制"是基数——标签组合总数决定 Prometheus 的内存与查询性能。
硬性规则
- 标签名:字母/下划线开头,只含字母、数字、下划线;这是 legacy 名称规则;UTF-8 模式下可接受更广字符,PromQL 中需按语法引用,采集端也须支持;
- 保留前缀:
__前缀保留;目标 relabel 阶段的内部标签(如__address__)在该阶段结束后移除,不能据此认为指标名使用的__name__也会被一律丢弃; - 传统指标名规则允许额外的冒号,冒号通常保留给录制规则;不完全同标签名;
- 标签值: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__=~".+"})) 取前几名审查。