feat: add MetricMetadata.Builder, deprecate wide constructors (#2202)

## Summary

- Adds `MetricMetadata.builder()` with `name`, `help`, `unit`,
`counterSuffix` fields
- Builder appends unit to the base name when absent, and appends
`_total` to `expositionBaseName` when `counterSuffix=true`
- Deprecates the 4-arg and 5-arg constructors; internal callers
(`MetricMetadataSupport`, `MetricMetadata.escape`) suppress the warning
- Updates `docs/apidiffs/current_vs_latest/prometheus-metrics-model.txt`

## Motivation

The OTel exporter
([opentelemetry/opentelemetry-java#8346](open-telemetry/opentelemetry-java#8346))
needs to express per-strategy counter intent without pre-computing
`expositionBaseName` manually. The builder encapsulates that logic and
provides a cleaner public API for any downstream adapter that constructs
`MetricMetadata` directly.

## Test plan

- [ ] `MetricMetadataTest` — 8 new builder tests covering: no unit, unit
absent/present, counter suffix, counter + unit, UTF-8 name, non-counter,
name-required validation
- [ ] Existing 4-arg/5-arg constructor tests annotated with
`@SuppressWarnings("deprecation")`

---------

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Author: zeitlinger

docs/apidiffs/current_vs_latest/prometheus-metrics-model.txt

@@ -36,7 +36,13 @@ protected MetricWithFixedMetadata(Builder<?, ?> builder) {
     String originalName = builder.originalName;
     String expositionBaseName = makeExpositionBaseName(originalName, builder.unit);
     this.metadata =
-        new MetricMetadata(name, expositionBaseName, originalName, builder.help, builder.unit);
+        MetricMetadata.builder()
+            .name(name)
+            .expositionBaseName(expositionBaseName)
+            .originalName(originalName)
+            .help(builder.help)
+            .unit(builder.unit)
+            .build();
     this.labelNames = Arrays.copyOf(builder.labelNames, builder.labelNames.length);
   }
 

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

@@ -5,7 +5,6 @@
 import javax.annotation.Nullable;
 
 /** Immutable container for metric metadata: name, help, unit. */
-@StableApi
 public final class MetricMetadata {
 
   /**
@@ -51,11 +50,13 @@ public final class MetricMetadata {
   @Nullable private final Unit unit;
 
   /** See {@link #MetricMetadata(String, String, Unit)} */
+  @StableApi
   public MetricMetadata(String name) {
     this(name, null, null);
   }
 
   /** See {@link #MetricMetadata(String, String, Unit)} */
+  @StableApi
   public MetricMetadata(String name, String help) {
     this(name, help, null);
   }
@@ -69,10 +70,116 @@ public MetricMetadata(String name, String help) {
    * @param help optional. May be {@code null}.
    * @param unit optional. May be {@code null}.
    */
+  @StableApi
   public MetricMetadata(String name, @Nullable String help, @Nullable Unit unit) {
     this(name, name, help, unit);
   }
 
+  /**
+   * Creates a builder for {@link MetricMetadata}.
+   *
+   * <p>Use the builder instead of the multi-arg constructors for cleaner, more readable code:
+   *
+   * <pre>{@code
+   * MetricMetadata.builder()
+   *     .name("http_requests")
+   *     .help("Total HTTP requests")
+   *     .unit(Unit.BYTES)
+   *     .counterSuffix(true)
+   *     .build();
+   * }</pre>
+   */
+  @StableApi
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  /** Builder for {@link MetricMetadata}. */
+  public static final class Builder {
+    @Nullable private String name;
+    @Nullable private String expositionBaseName;
+    @Nullable private String originalName;
+    @Nullable private String help;
+    @Nullable private Unit unit;
+    private boolean counterSuffix;
+
+    private Builder() {}
+
+    /** Required. The base metric name (without type suffix like {@code _total}). */
+    @StableApi
+    public Builder name(String name) {
+      this.name = name;
+      if (originalName == null) {
+        this.originalName = name;
+      }
+      return this;
+    }
+
+    /**
+     * Internal use only. Not part of the stable API.
+     *
+     * <p>Allows internal callers to preserve a separate exposition base name.
+     */
+    public Builder expositionBaseName(String expositionBaseName) {
+      this.expositionBaseName = expositionBaseName;
+      return this;
+    }
+
+    /**
+     * Internal use only. Not part of the stable API.
+     *
+     * <p>Allows internal callers to preserve the raw name before normalization.
+     */
+    public Builder originalName(String originalName) {
+      this.originalName = originalName;
+      return this;
+    }
+
+    /** Optional. Human-readable description of the metric. */
+    @StableApi
+    public Builder help(@Nullable String help) {
+      this.help = help;
+      return this;
+    }
+
+    /** Optional. The unit of measurement. Appended to the name if not already present. */
+    @StableApi
+    public Builder unit(@Nullable Unit unit) {
+      this.unit = unit;
+      return this;
+    }
+
+    /**
+     * Optional. When {@code true}, the writer appends {@code _total} to the exposition name. Use
+     * this for counter metrics, especially UTF-8 names where the writer cannot infer it from the
+     * snapshot type alone.
+     */
+    @StableApi
+    public Builder counterSuffix(boolean counterSuffix) {
+      this.counterSuffix = counterSuffix;
+      return this;
+    }
+
+    /** Builds the {@link MetricMetadata}. Throws if {@code name} was not set. */
+    @StableApi
+    public MetricMetadata build() {
+      if (name == null) {
+        throw new IllegalArgumentException("name is required");
+      }
+      String baseName = appendUnitIfMissing(name, unit);
+      String originalName = this.originalName == null ? name : this.originalName;
+      String expositionBaseName =
+          appendUnitIfMissing(
+              this.expositionBaseName == null ? baseName : this.expositionBaseName, unit);
+      if (counterSuffix
+          && !expositionBaseName.endsWith("_total")
+          && !expositionBaseName.endsWith(".total")) {
+        expositionBaseName = expositionBaseName + "_total";
+      }
+      return new MetricMetadata(baseName, expositionBaseName, originalName, help, unit);
+    }
+  }
+
   /**
    * Constructor with exposition base name.
    *
@@ -82,7 +189,10 @@ public MetricMetadata(String name, @Nullable String help, @Nullable Unit unit) {
    *     format writers for smart-append logic
    * @param help optional. May be {@code null}.
    * @param unit optional. May be {@code null}.
+   * @deprecated Use {@link #builder()} instead.
    */
+  @StableApi
+  @Deprecated
   public MetricMetadata(
       String name, String expositionBaseName, @Nullable String help, @Nullable Unit unit) {
     this(name, expositionBaseName, expositionBaseName, help, unit);
@@ -97,7 +207,10 @@ public MetricMetadata(
    * @param originalName the raw name as provided by the user, before any modification
    * @param help optional. May be {@code null}.
    * @param unit optional. May be {@code null}.
+   * @deprecated Use {@link #builder()} instead.
    */
+  @StableApi
+  @Deprecated
   public MetricMetadata(
       String name,
       String expositionBaseName,
@@ -121,6 +234,7 @@ public MetricMetadata(
    * <p>The name may contain any Unicode chars. Use {@link #getPrometheusName()} to get the name in
    * legacy Prometheus format, i.e. with all dots and all invalid chars replaced by underscores.
    */
+  @StableApi
   public String getName() {
     return name;
   }
@@ -130,6 +244,7 @@ public String getName() {
    *
    * <p>This is used by Prometheus exposition formats.
    */
+  @StableApi
   public String getPrometheusName() {
     return prometheusName;
   }
@@ -139,6 +254,7 @@ public String getPrometheusName() {
    * called {@code Counter.builder().name("req").unit(BYTES)}, this returns "req" while {@link
    * #getName()} returns "req_bytes" and {@link #getExpositionBaseName()} returns "req_bytes".
    */
+  @StableApi
   public String getOriginalName() {
     return originalName;
   }
@@ -148,6 +264,7 @@ public String getOriginalName() {
    * if the user called {@code Counter.builder().name("events_total")}, this returns "events_total"
    * while {@link #getName()} returns "events".
    */
+  @StableApi
   public String getExpositionBaseName() {
     return expositionBaseName;
   }
@@ -156,24 +273,35 @@ public String getExpositionBaseName() {
    * Same as {@link #getExpositionBaseName()} but with all invalid characters and dots replaced by
    * underscores.
    */
+  @StableApi
   public String getExpositionBasePrometheusName() {
     return expositionBasePrometheusName;
   }
 
+  @StableApi
   @Nullable
   public String getHelp() {
     return help;
   }
 
+  @StableApi
   public boolean hasUnit() {
     return unit != null;
   }
 
+  @StableApi
   @Nullable
   public Unit getUnit() {
     return unit;
   }
 
+  private static String appendUnitIfMissing(String name, @Nullable Unit unit) {
+    if (unit != null && !name.endsWith("_" + unit) && !name.endsWith("." + unit)) {
+      return name + "_" + unit;
+    }
+    return name;
+  }
+
   private void validate() {
     if (name == null) {
       throw new IllegalArgumentException("Missing required field: name is null");
@@ -206,11 +334,12 @@ private void validate() {
   }
 
   MetricMetadata escape(EscapingScheme escapingScheme) {
-    return new MetricMetadata(
-        PrometheusNaming.escapeName(name, escapingScheme),
-        PrometheusNaming.escapeName(expositionBaseName, escapingScheme),
-        PrometheusNaming.escapeName(originalName, escapingScheme),
-        help,
-        unit);
+    return MetricMetadata.builder()
+        .name(PrometheusNaming.escapeName(name, escapingScheme))
+        .expositionBaseName(PrometheusNaming.escapeName(expositionBaseName, escapingScheme))
+        .originalName(PrometheusNaming.escapeName(originalName, escapingScheme))
+        .help(help)
+        .unit(unit)
+        .build();
   }
 }

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/MetricMetadata.java

@@ -25,12 +25,13 @@ private static MetricMetadata typedMetadata(
       String suffix,
       String dotSuffix) {
     String baseName = stripSuffix(originalName, suffix, dotSuffix);
-    return new MetricMetadata(
-        appendUnitIfMissing(baseName, unit),
-        appendUnitIfMissing(originalName, unit),
-        originalName,
-        help,
-        unit);
+    return MetricMetadata.builder()
+        .name(appendUnitIfMissing(baseName, unit))
+        .expositionBaseName(appendUnitIfMissing(originalName, unit))
+        .originalName(originalName)
+        .help(help)
+        .unit(unit)
+        .build();
   }
 
   private static String appendUnitIfMissing(String name, @Nullable Unit unit) {