Prometheus Client指定标签值报错：标签数量不匹配问题排查

核心问题 #

你错误地将包含两个元素的列表/元组作为单个参数传递给labels()方法，导致Prometheus Client认为你只提供了1个标签值，与定义的2个标签（color、orientation）不匹配，触发ValueError。

错误示例 #

from prometheus_client import Gauge

# 定义带两个标签的Gauge
my_gauge = Gauge('object_status', 'Status of objects with color and orientation', ['color', 'orientation'])

# ❌ 错误：将列表作为单个参数传入，仅被识别为1个标签值
my_gauge.labels(['red', 'horizontal']).set(1)
# 或 ❌ 元组同理
my_gauge.labels(('blue', 'vertical')).set(2)

正确写法 #

你需要将列表/元组中的元素解包为独立参数传递，或者直接按标签名/顺序传值：

• 方式1：用*解包列表/元组

# ✅ 解包列表，传递两个独立参数
my_gauge.labels(*['red', 'horizontal']).set(1)
# ✅ 解包元组同理
my_gauge.labels(*('blue', 'vertical')).set(2)

• 方式2：按标签名传关键字参数

# ✅ 明确指定每个标签的值
my_gauge.labels(color='red', orientation='horizontal').set(1)

• 方式3：按标签定义顺序传位置参数

# ✅ 按['color', 'orientation']的顺序传值
my_gauge.labels('red', 'horizontal').set(1)

原理说明 #

Prometheus Python Client的labels()方法要求传入的参数数量必须与指标定义的标签数量完全一致。如果直接传入列表/元组，它会被当作第一个标签的取值，而非多个标签值的集合，自然会出现“标签数量为1（实际应为2）”的错误。

内容的提问来源于stack exchange，提问作者Luc De Graef