feat: add typed metric family descriptors

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

@@ -90,10 +90,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

@@ -92,10 +92,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

@@ -647,10 +647,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

@@ -105,7 +105,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 {
@@ -120,7 +120,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]);
             }
@@ -171,7 +171,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));
     }

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

@@ -116,10 +116,15 @@ protected SummarySnapshot 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 SummarySnapshot(getMetadata(), data);
+    return new SummarySnapshot(metadata, data);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.SUMMARY;
   }

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

@@ -61,10 +61,15 @@ public SummarySnapshot collect() {
               new SummarySnapshot.SummaryDataPointSnapshot(
                   count, sum, quantiles, makeLabels(labelValues), Exemplars.EMPTY, 0L));
         });
-    return new SummarySnapshot(getMetadata(), dataPoints);
+    return new SummarySnapshot(metadata, dataPoints);
   }
 
+  /**
+   * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+   */
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public MetricType getMetricType() {
     return MetricType.SUMMARY;
   }

prometheus-metrics-core/src/test/java/io/prometheus/metrics/core/metrics/MetricWithFixedMetadataTest.java

@@ -0,0 +1,75 @@
+package io.prometheus.metrics.core.metrics;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import io.prometheus.metrics.config.PrometheusProperties;
+import io.prometheus.metrics.model.registry.MetricType;
+import io.prometheus.metrics.model.snapshots.Labels;
+import io.prometheus.metrics.model.snapshots.MetricFamilyDescriptor;
+import io.prometheus.metrics.model.snapshots.MetricSnapshot;
+import java.util.Collections;
+import org.junit.jupiter.api.Test;
+
+class MetricWithFixedMetadataTest {
+
+  @Test
+  @SuppressWarnings("deprecation")
+  void getMetricFamilyDescriptorAdaptsDeprecatedMetricTypeOverride() {
+    LegacyMetric metric =
+        LegacyMetric.builder()
+            .name("legacy.metric")
+            .constLabels(Labels.of("const.label", "value"))
+            .labelNames("dynamic.label")
+            .build();
+
+    MetricFamilyDescriptor descriptor = metric.getMetricFamilyDescriptor();
+
+    assertThat(descriptor).isNotNull();
+    assertThat(descriptor.getType()).isEqualTo(MetricType.GAUGE);
+    assertThat(descriptor.getPrometheusName()).isEqualTo("legacy_metric");
+    assertThat(descriptor.getLabelNames())
+        .containsExactlyInAnyOrder("const_label", "dynamic_label");
+  }
+
+  private static class LegacyMetric extends MetricWithFixedMetadata {
+
+    private LegacyMetric(Builder builder) {
+      super(builder);
+    }
+
+    private static Builder builder() {
+      return new Builder();
+    }
+
+    @Override
+    public MetricSnapshot collect() {
+      throw new UnsupportedOperationException();
+    }
+
+    /**
+     * @deprecated Use {@link #getMetricFamilyDescriptor()} instead.
+     */
+    @Override
+    @Deprecated
+    public MetricType getMetricType() {
+      return MetricType.GAUGE;
+    }
+
+    private static class Builder extends MetricWithFixedMetadata.Builder<Builder, LegacyMetric> {
+
+      private Builder() {
+        super(Collections.emptyList(), PrometheusProperties.builder().build());
+      }
+
+      @Override
+      public LegacyMetric build() {
+        return new LegacyMetric(this);
+      }
+
+      @Override
+      protected Builder self() {
+        return this;
+      }
+    }
+  }
+}

prometheus-metrics-exposition-formats/src/test/java/io/prometheus/metrics/expositionformats/DuplicateNamesProtobufTest.java

@@ -19,7 +19,7 @@
 import java.util.List;
 import org.junit.jupiter.api.Test;
 
-@SuppressWarnings("NonCanonicalType")
+@SuppressWarnings({"NonCanonicalType", "deprecation"})
 class DuplicateNamesProtobufTest {
 
   private static PrometheusRegistry getPrometheusRegistry() {

prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java

@@ -61,6 +61,9 @@ public Builder setIncludeCreatedTimestamps(boolean includeCreatedTimestamps) {
       return this;
     }
 
+    /**
+     * @deprecated Use {@link #build()} with the default millisecond timestamps instead.
+     */
     @Deprecated
     public Builder setTimestampsInMs(boolean timestampsInMs) {
       this.timestampsInMs = timestampsInMs;