feat: add typed metric family descriptors (#2114)

Adds typed metric family descriptors and typed metadata support for the
model snapshots.

This is the typed-descriptor branch for downstreams that want to provide
registration-time metadata explicitly. The #1800
Collector/MultiCollector registration metadata hooks are already
optional via default methods, so unmodified downstreams should not need
this PR just to keep working.

This PR now also deprecates the fragmented registration metadata API
(`getPrometheusName()`, `getMetricType()`, `getLabelNames()`, and
`getMetadata()` plus the `MultiCollector` variants) in favor of
`getMetricFamilyDescriptor()` / `getMetricFamilyDescriptors()`. The
deprecated methods remain bridged by default implementations for
compatibility.

Related validation:

- #2121 validates unmodified Micrometer independently of #2114, against
`main` + #2124.
- #2123 validates a Micrometer branch that explicitly uses
`MetricFamilyDescriptor` to implement the existing registration metadata
hooks without invoking scrape/sample callbacks during registration.

---------

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

Author: zeitlinger

examples/example-exporter-multi-target/src/main/java/io/prometheus/metrics/examples/multitarget/SampleMultiCollector.java

@@ -77,7 +77,12 @@ protected MetricSnapshots collectMetricSnapshots(PrometheusScrapeRequest scrapeR
     return new MetricSnapshots(snaps);
   }
 
+  /**
+   * @deprecated Use {@code getMetricFamilyDescriptors()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public List<String> getPrometheusNames() {
     List<String> names = new ArrayList<String>();
     names.add("x_calls_total");

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Counter.java

@@ -93,10 +93,15 @@ protected CounterSnapshot collect(List<Labels> labels, List<DataPoint> metricDat
     for (int i = 0; i < labels.size(); i++) {
       data.add(metricData.get(i).collect(labels.get(i)));
     }
-    return new CounterSnapshot(getMetadata(), data);
+    return new CounterSnapshot(metadata, data);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.COUNTER;
   }

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/CounterWithCallback.java

@@ -48,10 +48,15 @@ public CounterSnapshot collect() {
               new CounterSnapshot.CounterDataPointSnapshot(
                   value, makeLabels(labelValues), null, 0L));
         });
-    return new CounterSnapshot(getMetadata(), dataPoints);
+    return new CounterSnapshot(metadata, dataPoints);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.COUNTER;
   }

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Gauge.java

@@ -95,10 +95,15 @@ protected GaugeSnapshot collect(List<Labels> labels, List<DataPoint> metricData)
     for (int i = 0; i < labels.size(); i++) {
       dataPointSnapshots.add(metricData.get(i).collect(labels.get(i)));
     }
-    return new GaugeSnapshot(getMetadata(), dataPointSnapshots);
+    return new GaugeSnapshot(metadata, dataPointSnapshots);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.GAUGE;
   }

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/GaugeWithCallback.java

@@ -52,10 +52,15 @@ public GaugeSnapshot collect() {
           dataPoints.add(
               new GaugeSnapshot.GaugeDataPointSnapshot(value, makeLabels(labelValues), null, 0L));
         });
-    return new GaugeSnapshot(getMetadata(), dataPoints);
+    return new GaugeSnapshot(metadata, dataPoints);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.GAUGE;
   }

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Histogram.java

@@ -650,10 +650,15 @@ protected HistogramSnapshot collect(List<Labels> labels, List<DataPoint> metricD
     for (int i = 0; i < labels.size(); i++) {
       data.add(metricData.get(i).collect(labels.get(i)));
     }
-    return new HistogramSnapshot(getMetadata(), data);
+    return new HistogramSnapshot(metadata, data);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.HISTOGRAM;
   }

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Info.java

@@ -48,7 +48,7 @@ public void setLabelValues(String... labelValues) {
       throw new IllegalArgumentException(
           getClass().getSimpleName()
               + " "
-              + getMetadata().getName()
+              + metadata.getName()
               + " was created with "
               + labelNames.length
               + " label names, but you called setLabelValues() with "
@@ -66,7 +66,7 @@ public void addLabelValues(String... labelValues) {
       throw new IllegalArgumentException(
           getClass().getSimpleName()
               + " "
-              + getMetadata().getName()
+              + metadata.getName()
               + " was created with "
               + labelNames.length
               + " label names, but you called addLabelValues() with "
@@ -82,7 +82,7 @@ public void remove(String... labelValues) {
       throw new IllegalArgumentException(
           getClass().getSimpleName()
               + " "
-              + getMetadata().getName()
+              + metadata.getName()
               + " was created with "
               + labelNames.length
               + " label names, but you called remove() with "
@@ -103,10 +103,15 @@ public InfoSnapshot collect() {
         data.add(new InfoSnapshot.InfoDataPointSnapshot(label.merge(constLabels)));
       }
     }
-    return new InfoSnapshot(getMetadata(), data);
+    return new InfoSnapshot(metadata, data);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.INFO;
   }

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/MetricWithFixedMetadata.java

@@ -1,8 +1,10 @@
 package io.prometheus.metrics.core.metrics;
 
 import io.prometheus.metrics.config.PrometheusProperties;
+import io.prometheus.metrics.model.registry.MetricType;
 import io.prometheus.metrics.model.snapshots.Label;
 import io.prometheus.metrics.model.snapshots.Labels;
+import io.prometheus.metrics.model.snapshots.MetricFamilyDescriptor;
 import io.prometheus.metrics.model.snapshots.MetricMetadata;
 import io.prometheus.metrics.model.snapshots.PrometheusNaming;
 import io.prometheus.metrics.model.snapshots.Unit;
@@ -20,7 +22,7 @@
  */
 public abstract class MetricWithFixedMetadata extends Metric {
 
-  private final MetricMetadata metadata;
+  protected final MetricMetadata metadata;
   protected final String[] labelNames;
 
   protected MetricWithFixedMetadata(Builder<?, ?> builder) {
@@ -37,6 +39,22 @@ protected MetricWithFixedMetadata(Builder<?, ?> builder) {
   }
 
   @Override
+  @Nullable
+  @SuppressWarnings("deprecation")
+  public MetricFamilyDescriptor getMetricFamilyDescriptor() {
+    MetricType metricType = getMetricType();
+    if (metricType == null) {
+      return null;
+    }
+    return MetricFamilyDescriptor.of(metricType, metadata, getPrometheusLabels());
+  }
+
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
+  @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricMetadata getMetadata() {
     return metadata;
   }
@@ -65,13 +83,27 @@ private String makeExpositionBaseName(@Nullable String expositionBaseName, @Null
     return expositionBaseName;
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public String getPrometheusName() {
     return metadata.getPrometheusName();
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public Set<String> getLabelNames() {
+    return getPrometheusLabels();
+  }
+
+  private Set<String> getPrometheusLabels() {
     Set<String> names = new HashSet<>();
     for (String labelName : labelNames) {
       names.add(PrometheusNaming.prometheusName(labelName));

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StateSet.java

@@ -60,7 +60,7 @@ private StateSet(Builder builder, String[] names) {
     super(builder);
     this.names = names;
     for (String name : names) {
-      if (this.getMetadata().getPrometheusName().equals(prometheusName(name))) {
+      if (metadata.getPrometheusName().equals(prometheusName(name))) {
         throw new IllegalArgumentException(
             "Label name "
                 + name
@@ -82,10 +82,15 @@ protected StateSetSnapshot collect(List<Labels> labels, List<DataPoint> metricDa
           new StateSetSnapshot.StateSetDataPointSnapshot(
               names, metricDataList.get(i).values, labels.get(i)));
     }
-    return new StateSetSnapshot(getMetadata(), data);
+    return new StateSetSnapshot(metadata, data);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.STATESET;
   }

prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StatefulMetric.java

@@ -106,7 +106,7 @@ public D labelValues(String... labelValues) {
         throw new IllegalArgumentException(
             getClass().getSimpleName()
                 + " "
-                + getMetadata().getName()
+                + metadata.getName()
                 + " was created with label names, so you must call labelValues(...)"
                 + " when using it.");
       } else {
@@ -121,7 +121,7 @@ public D labelValues(String... labelValues) {
             if (l.get(i) == null) {
               throw new IllegalArgumentException(
                   "null label value for metric "
-                      + getMetadata().getName()
+                      + metadata.getName()
                       + " and label "
                       + labelNames[i]);
             }
@@ -172,7 +172,7 @@ protected MetricsProperties[] getMetricProperties(
     if (Objects.equals(builder.exemplarsEnabled, false)) {
       properties.add(MetricsProperties.builder().exemplarsEnabled(false).build());
     }
-    String metricName = getMetadata().getName();
+    String metricName = metadata.getName();
     if (prometheusProperties.getMetricProperties(metricName) != null) {
       properties.add(prometheusProperties.getMetricProperties(metricName));
     }