本文旨在深入解析micrometer與prometheus集成時常見的“所有同名度量指標(biāo)必須擁有相同的標(biāo)簽鍵集合”錯誤。我們將探討該錯誤產(chǎn)生的根本原因，即多個組件或自定義切面為同一指標(biāo)名注冊了不同標(biāo)簽鍵集合的計時器。文章將提供多種解決方案，包括確保標(biāo)簽鍵一致性、使用不同指標(biāo)名或精細(xì)控制切面應(yīng)用范圍，并強調(diào)高基數(shù)標(biāo)簽（如uri）的潛在危害及規(guī)避方法。

理解Prometheus度量模型與標(biāo)簽鍵一致性

在使用Micrometer結(jié)合Prometheus進(jìn)行應(yīng)用監(jiān)控時，一個核心原則是：Prometheus要求所有具有相同名稱的度量指標(biāo)必須擁有相同的標(biāo)簽鍵集合。 這意味著，對于任何給定的度量指標(biāo)名稱（例如 http_requests_total），無論其標(biāo)簽值如何變化，其關(guān)聯(lián)的標(biāo)簽鍵（例如 method, path, status）必須是固定不變的。

為什么會有這個限制？ Prometheus將一個度量指標(biāo)的名稱與它的一組標(biāo)簽鍵視為一個唯一的“時間序列”定義。當(dāng)Prometheus抓取數(shù)據(jù)時，它期望這些時間序列的結(jié)構(gòu)是穩(wěn)定的。如果同一個指標(biāo)名在不同的注冊點擁有不同的標(biāo)簽鍵集合，Prometheus將無法正確地將其識別為同一個邏輯度量，從而導(dǎo)致數(shù)據(jù)模型混亂，并可能引發(fā) IllegalArgumentException。

例如，如果您注冊了一個名為 my_timer 的計時器，帶有標(biāo)簽 [tagA, tagB]，然后又嘗試注冊一個名為 my_timer 的計時器，帶有標(biāo)簽 [tagA, tagC]，Prometheus就會拋出上述異常，因為它認(rèn)為這兩個 my_timer 具有不同的結(jié)構(gòu)。

案例分析：自定義AOP切面中的標(biāo)簽鍵沖突

在提供的案例中，用戶遇到了以下錯誤信息： 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].

這個錯誤清晰地指出了問題：

1. 存在一個名為 web_photos_gotten_list_seconds 的計時器。
2. 它已經(jīng)被注冊過，帶有的標(biāo)簽鍵是 [class, exception, method]。
3. 現(xiàn)在有另一個代碼路徑嘗試注冊同名計時器，但帶有的標(biāo)簽鍵是 [exception, method, outcome, status, uri]。

根本原因分析： 在Spring Boot應(yīng)用中，當(dāng)您自定義一個AOP切面來處理 @Timed 注解時，很可能與Spring Boot默認(rèn)提供的 TimedAspect 產(chǎn)生沖突。

• 用戶自定義的 TargetedTimedAspect： 根據(jù)提供的代碼，該切面在構(gòu)建 Timer.Builder 時，默認(rèn)會添加 tagsBasedOnJoinPoint.apply(pjp)，這通常會包含 class 和 method 標(biāo)簽。此外，它還會添加 EXCEPTION_TAG (exception)。因此，它注冊的計時器通常包含 [class, exception, method] 等標(biāo)簽。對于 StreamListener 和 Scheduled 方法，還會額外添加 BINDING_TAG 或 SCHEDULED_CRON_TAG。
• Spring Boot默認(rèn)的 TimedAspect (或其它框架/自定義切面)： 對于HTTP請求等場景，Spring Boot默認(rèn)的 TimedAspect 會自動為 @Timed 注解的方法生成度量指標(biāo)，并添加與HTTP請求相關(guān)的標(biāo)簽，例如 outcome (成功/失敗), status (HTTP狀態(tài)碼), uri (請求URI) 等。這些標(biāo)簽與用戶自定義切面中的標(biāo)簽集合不同。

當(dāng)一個方法（例如 webPhotosGottenList()）同時滿足兩個切面的條件（例如，它是一個帶有 @Timed 注解的Web控制器方法），并且兩個切面都嘗試為它注冊一個名為 web_photos_gotten_list_seconds 的計時器時，就會發(fā)生標(biāo)簽鍵集合不一致的沖突。

Pointcut的作用： 用戶在問題中提到，通過修改 Pointcut，問題得到了解決。這并非偶然。最初的 @Around("timedAnnotatedPointcut()") 會使得自定義切面應(yīng)用于所有帶有 @Timed 注解的方法。如果其中一些方法也是Web請求處理器，那么它們就會被Spring Boot的默認(rèn)切面和用戶自定義切面同時處理。

修改后的 Pointcut： @Around("timedAnnotatedPointcut() && (asyncAnnotatedPointcut() || allowedMethodPointcut())") 這個修改限制了自定義切面的應(yīng)用范圍，使其僅作用于那些帶有 @Timed 且同時是 @StreamListener、@Scheduled 或特定服務(wù)方法的方法。如果 webPhotosGottenList() 方法不屬于這些類別，那么用戶自定義的切面將不再對其生效，從而避免了與Spring Boot默認(rèn)切面為該方法注冊的計時器發(fā)生標(biāo)簽鍵沖突。

解決方案

解決此類標(biāo)簽鍵沖突問題有以下幾種策略：

1. 確保所有注冊點的標(biāo)簽鍵集合一致

這是最根本的解決方案。對于同一個度量指標(biāo)名稱，必須確保所有嘗試注冊它的代碼路徑都使用完全相同的標(biāo)簽鍵集合。

• 統(tǒng)一標(biāo)簽定義： 審查所有可能注冊 web_photos_gotten_list_seconds 的代碼。如果某些標(biāo)簽并非總是適用，可以為它們設(shè)置一個默認(rèn)值（例如 "none" 或 "N/A"），而不是完全省略這些標(biāo)簽。

• 示例： 如果一個計時器有時需要 outcome 和 status 標(biāo)簽，而有時不需要，那么在不需要的場景下，也必須添加這些標(biāo)簽，并賦予一個默認(rèn)值。

  // 確保所有注冊點都有相同的標(biāo)簽鍵
  Timer.Builder timerBuilder = Timer.builder(metricName)
      .tags(EXCEPTION_TAG, exceptionClass)
      .tags(tagsBasedOnJoinPoint.apply(pjp)); // 包含 class, method
  
  // 假設(shè) outcome, status, uri 也是需要統(tǒng)一的標(biāo)簽
  // 如果當(dāng)前上下文沒有這些值，也要添加默認(rèn)值
  timerBuilder.tag("outcome", "unknown");
  timerBuilder.tag("status", "unknown");
  timerBuilder.tag("uri", "unknown"); // 注意：URI標(biāo)簽應(yīng)謹(jǐn)慎使用，見下方最佳實踐
  
  if (streamListener != null) {
      timerBuilder.tags(BINDING_TAG, streamListener.value().isEmpty() ? streamListener.target() : streamListener.value());
      timerBuilder.tag(SCHEDULED_CRON_TAG, "none"); // 確保cron標(biāo)簽也存在
  } else if (scheduled != null) {
      timerBuilder.tags(SCHEDULED_CRON_TAG, scheduled.cron());
      timerBuilder.tag(BINDING_TAG, "none"); // 確保binding標(biāo)簽也存在
  } else {
      timerBuilder.tag(BINDING_TAG, "none");
      timerBuilder.tag(SCHEDULED_CRON_TAG, "none");
  }
  
  sample.stop(timerBuilder.register(registry));

  登錄后復(fù)制

  這種方法可能導(dǎo)致度量指標(biāo)的標(biāo)簽數(shù)量增多，但能保證一致性。

  

  神卷標(biāo)書

  神卷標(biāo)書，專注于AI智能標(biāo)書制作、管理與咨詢服務(wù)，提供高效、專業(yè)的招投標(biāo)解決方案。支持一站式標(biāo)書生成、模板下載，助力企業(yè)輕松投標(biāo)，提升中標(biāo)率。

  5

  查看詳情

2. 為不同的邏輯度量使用不同的指標(biāo)名稱

如果兩個具有相同名稱但不同標(biāo)簽集合的度量指標(biāo)實際上代表了不同的業(yè)務(wù)或技術(shù)含義，那么它們就不應(yīng)該共享同一個名稱。

• 區(qū)分命名： 例如，如果 web_photos_gotten_list_seconds 既用于Web請求又用于內(nèi)部異步任務(wù)，可以將其命名為 web_photos_gotten_list_http_seconds 和 web_photos_gotten_list_async_seconds。這樣，即使它們有不同的標(biāo)簽集合，也不會沖突。

3. 精細(xì)控制AOP切面的應(yīng)用范圍或禁用沖突的注冊

如果沖突是由多個AOP切面（例如自定義切面與Spring Boot默認(rèn)切面）同時作用于同一方法引起的，可以通過調(diào)整切面配置來解決。

• 限制自定義切面范圍： 如案例所示，通過更精確的 Pointcut 表達(dá)式，確保自定義切面只應(yīng)用于您希望它處理的方法，避免與Spring Boot或其他框架的默認(rèn)切面重疊。

  // 示例：僅對特定服務(wù)層方法或特定注解方法應(yīng)用自定義切面
  @Around("timedAnnotatedPointcut() && (asyncAnnotatedPointcut() || allowedMethodPointcut())")
  public Object timedMethod(ProceedingJoinPoint pjp) throws Throwable {
      // ... 自定義計時邏輯
  }

  登錄后復(fù)制
• 禁用默認(rèn)切面： 如果您的自定義切面已經(jīng)提供了所有必要的度量功能，并且與Spring Boot的默認(rèn) TimedAspect 沖突，您可以考慮禁用默認(rèn)的自動配置。例如，對于Web請求計時，可以通過配置屬性禁用。

4. 調(diào)試查找沖突源

當(dāng)不確定是哪個代碼路徑注冊了沖突的度量指標(biāo)時，可以使用調(diào)試工具：

• 設(shè)置條件斷點： 在 io.micrometer.core.instrument.MeterRegistry 的 register() 方法上設(shè)置一個條件斷點，條件是 meter.getId().getName().equals("web_photos_gotten_list_seconds")。當(dāng)程序執(zhí)行到這里時，您可以檢查調(diào)用棧，找出是哪個組件或代碼行嘗試注冊該度量指標(biāo)。

最佳實踐與注意事項

1. 高基數(shù)標(biāo)簽的危害： 錯誤信息中出現(xiàn)的 uri 標(biāo)簽是一個需要特別注意的問題。URI通常具有非常高的基數(shù)（即可能的值非常多）。將高基數(shù)標(biāo)簽添加到Prometheus度量指標(biāo)會導(dǎo)致：

   • 內(nèi)存消耗： Prometheus服務(wù)器需要為每個唯一的標(biāo)簽組合存儲一個時間序列，高基數(shù)標(biāo)簽會迅速耗盡服務(wù)器內(nèi)存。
   • 查詢性能： 大量時間序列會嚴(yán)重影響查詢性能。
   • 數(shù)據(jù)膨脹： 導(dǎo)致存儲數(shù)據(jù)量劇增。
   • 解決方案： 避免直接使用完整的URI作為標(biāo)簽?？梢钥紤]：
     • URI模板化： 將動態(tài)部分替換為占位符（例如 /users/{id} 變?yōu)?/users/{id}）。
     • 固定路徑段： 只使用URI的第一個或前幾個路徑段。
     • 使用 MeterFilter： 在Micrometer層面過濾或修改高基數(shù)標(biāo)簽。

2. 默認(rèn)行為與自定義： 在Spring Boot環(huán)境中，理解框架的默認(rèn)度量行為至關(guān)重要。當(dāng)您引入自定義度量邏輯時，要清楚它是否會與默認(rèn)行為重疊或沖突。

3. 清晰的命名約定： 為您的度量指標(biāo)制定清晰的命名約定，使其能夠區(qū)分不同類型或來源的度量。

總結(jié)

Prometheus對標(biāo)簽鍵一致性的要求是其數(shù)據(jù)模型的基礎(chǔ)。當(dāng)遇到“同名度量指標(biāo)必須擁有相同的標(biāo)簽鍵集合”錯誤時，核心任務(wù)是識別并解決不同代碼路徑為同一指標(biāo)名注冊了不同標(biāo)簽鍵集合的問題。通過確保標(biāo)簽鍵一致性、使用不同的指標(biāo)名稱、精細(xì)化AOP切面范圍或禁用沖突的度量注冊，可以有效地解決這類問題。同時，務(wù)必警惕高基數(shù)標(biāo)簽帶來的性能隱患，并采取適當(dāng)?shù)牟呗赃M(jìn)行規(guī)避。

以上就是Prometheus與Micrometer：解決度量指標(biāo)標(biāo)簽鍵沖突問題的詳細(xì)內(nèi)容，更多請關(guān)注php中文網(wǎng)其它相關(guān)文章！