Anpassung von Metriken mit demselben Namen aber verschiedenen Labels

Beim Start des Zustelldienstes Beim ersten Aufruf einer konfliktbehafteten, mit @Timed-annotierten Methode wird folgende Warnung ins Log geschrieben:

WARN: The meter (MeterId{name='method.timed', tags=[tag(class=de.fitko.zustelldienst.submissions.service.SubmissionSearchService),tag(exception=none),tag(method=getSubmittedSubmissionsForDestinations)]})
 registration has failed: Prometheus requires that all meters with the same name have the same set of tag keys.
 There is already an existing meter named 'method_timed_seconds' containing tag keys [attachment_of, class, exception, method].
 The meter you are attempting to register has keys [class, exception, method]. Note that subsequent logs will be logged at debug level.

Ursache ist die Definition von Metriken desselben Namens mit unterschiedlichen Label-Keys.
Z.B. ergibt die Verwendung der @Timed-Annotation ohne Angabe eines Metrik-Namens den Metriknamen "method.timed". Wird diese nun einmal ohne weitere Tags wie in SubmissionSearchService.getSubmittedSubmissionsForDestinations() oder BinaryLargeObjectService.cleanup() und einmal mit Tags wie in BinaryLargeObjectService.write() verwendet, so "gewinnt" vermutlich die erste Metrik und die andere wird gar nicht erst registriert.

Im Wesentlichen betrifft das Metriken von BinaryLargeObjectService, zum Beispiel:

@Timed(histogram = true, extraTags = {"attachment_of", "submission"})
public AttachmentMetadata write(Submission submission, UUID attachmentId, InputStream inputStream) throws BusinessException {

Unter Umständen sind aber weitere, programmatisch definierte Metriken betroffen.

Nochmal zur Klarstellung:

Erlaubt:

metrik_name_1{class="some",method="cleanup"}
metrik_name_1{class="other",method="perform"}

Nicht erlaubt:

metrik_name_2{class="some",method="cleanup",phase="shutdown"}
metrik_name_2{class="other",method="perform"}

Links, Hinweise, Bemerkungen

Zu dieser Problemstellung existiert das Micrometer Issue #877 (offen seit 9/2018) sowie Prometheus Java Client Issue #696 (offen seit 9/2021).

In den Kommentaren wird darüber diskutiert, ob Prometheus diesen Fall nun unterstützt oder nicht.
In der Dokumentation zu Prometheus findet sich aber ganz klar, dass dieselbe Metrik mit verschiedenen Labels nicht ermöglicht werden sollte:

Labels are one of the most powerful aspects of Prometheus, but easily abused. Accordingly client libraries must be very careful in how labels are offered to users. Client libraries MUST NOT allow users to have different label names for the same metric for Gauge/Counter/Summary/Histogram or any other Collector offered by the library.

Akzeptanzkriterien

1. Prüfung und ggf. Umstellung sämtlicher Metriken: Metriken, die dasselbe Set von Label-Keys verwenden, müssen zwingend denselben Namen verwenden.
   Die grundlegende Regel für @Timed lautet: "Sobald extraTags verwendet wird, muss ein Custom-Name verwendet werden."
2. Die eingangs erwähnte Warnung erscheint nicht mehr im Log und sämtliche Metriken sind registriert.
3. Interne Dokumentation dieser Tatsache bzw. unserer Konvention für Metriken für kommende Entwickler

Mögliche Folgeaktivitäten (vom Entwickler zu ergänzen)

• Ggf. Anpassung des ZSD Dashboards.