prometheus通过micrometer收集指标时，严格要求同名指标必须拥有完全一致的标签键集合。本文将深入探讨这一规则背后的原理，分析因自定义aop切面与框架默认指标注册冲突导致此问题的原因，并提供包括统一标签、使用不同指标名称及禁用冲突注册在内的多种解决方案，同时强调高基数标签的潜在风险。
在使用Micrometer集成Prometheus进行应用监控时，一个核心且严格的规则是：任何具有相同名称的指标（Meter）在注册时，必须包含完全一致的标签键集合。这意味着，如果一个名为 my_metric 的计时器（Timer）首先被注册时使用了 [tagA, tagB] 两个标签键，那么后续任何尝试注册同名 my_metric 的计时器，都必须且只能使用 [tagA, tagB] 这两个标签键。如果尝试注册 my_metric 时使用了 [tagA, tagC] 或 [tagA, tagB, tagD]，Micrometer将抛出 IllegalArgumentException，指出标签键集合不匹配。
这一规则的设立是为了确保监控数据的完整性、可预测性和查询效率。Prometheus在存储和查询指标时，将指标名称和标签键值对的组合视为一个唯一的时序数据序列。如果同名指标的标签键集合不一致，将导致数据模型混乱，查询结果不可靠，甚至可能引发性能问题。
在Spring Boot等框架中，Micrometer通常会被自动配置，对常见的组件（如Web请求、数据库访问）进行默认的指标收集。同时，开发者也可能通过自定义AOP切面（如 TargetedTimedAspect）来为特定业务逻辑或方法添加自定义的计时器指标。当这两种机制不经意间为同一个操作生成了同名但标签键集合不同的指标时，就会触发上述的 IllegalArgumentException。
以提供的 TargetedTimedAspect 代码为例：
@Aspect
@NonNullApi
public class TargetedTimedAspect {
public static final String DEFAULT_METRIC_NAME = "method.timed";
public static final String EXCEPTION_TAG = "exception";
private final MeterRegistry registry;
private final Function> tagsBasedOnJoinPoint;
public TargetedTimedAspect(MeterRegistry registry, Function> tagsBasedOnJoinPoint) {
this.registry = registry;
this.tagsBasedOnJoinPoint = tagsBasedOnJoinPoint;
}
@Around("timedAnnotatedPointcut() && (asyncAnnotatedPointcut() || allowedMethodPointcut())")
public Object timedMethod(ProceedingJoinPoint pjp) throws Throwable {
Method method = ((MethodSignature) pjp.getSignature()).getMethod();
Timed timed = method.getAnnotation(Timed.class);
// ... (获取或处理Timed注解)
final String metricName = timed.value().isEmpty() ? DEFAULT_METRIC_NAME : timed.value();
Timer.Sample sample = Timer.start(registry);
String exceptionClass = "none";
try {
return pjp.proceed();
} catch (Exception ex) {
exceptionClass = ex.getClass().getSimpleName();
throw ex;
} finally {
try {
Timer.Builder timerBuilder = Timer.builder(metricName)
.description(timed.description().isEmpty() ? null : timed.description())
.tags(timed.extraTags())
.tags(EXCEPTION_TAG, exceptionClass)
.tags(tagsBasedOnJoinPoint.apply(pjp)) // 默认添加 class 和 method 标签
// ... (根据StreamListener或Scheduled注解添加额外标签)
sample.stop(timerBuilder.register(registry));
} catch (Exception e) {
// ignoring on purpose
}
}
}
// ... (Pointcut定义)
} 在这个自定义切面中：
然而，错误信息 java.lang.IllegalArgumentException: Prometheus requires that all meters with the same name have the same set of tag keys. There is already an existing meter named 'web_photos_gotten_list_seconds' containing tag keys [class, exception, method]. The meter you are attempting to register has keys [exception, method, outcome, status, uri]. 清晰地表明：
由于这两个标签键集合不一致，Micrometer在注册第二个指标时抛出了异常。这与AOP的 Pointcut 定义本身无关，而是关于指标注册时标签键的匹配问题。
解决此问题的核心在于确保对于任何给定的指标名称，其所有注册都使用相同的标签键集合。
这是最直接的解决方案。您需要识别所有注册同名指标的来源，并确保它们在注册时都添加了完全相同的标签键。
修改自定义切面：如果框架默认注册的标签键是您希望保留的，那么修改您的 TargetedTimedAspect，使其在所有情况下都添加与框架默认注册一致的标签键。例如，如果 web_photos_gotten_list_seconds 应该包含 [exception, method, outcome, status, uri]，那么您的切面也需要添加 outcome, status, uri 等标签，并确保 class 标签不再出现（如果它不是通用标签）。这通常意味着您需要深入了解框架默认指标的标签生成逻辑。
示例调整 (假设目标标签为 [exception, method, outcome, status, uri])：
