Introduce meter conventions and apply to some JVM metrics (#6682)

Enable specifying a convention to control well-known metrics' names and tags.
Instrumentation can use this so its users can swap the convention applied without having to rewrite the instrumentation or resort to `MeterFilter` which can be more brittle.
The first use of this is in some of the JVM metrics instrumentations. Specifically, the instrumentation that covers the currently stable OpenTelemetry semantic conventions has been updated to utilize MeterConvention.
The default convention remains the same, although re-implemented using MeterConvention.
An additional implementation for each binder was added that matches the current version (1.37.0) of the OpenTelemetry semantic conventions for JVM metrics.
This allows users to configure Micrometer's JVM metrics instrumentation to use the stable OTel semantic conventions without the need for a `MeterFilter`.
Initial documentation has been added for this, which could be made more thorough in the future.

Author: shakuzen

docs/modules/ROOT/nav.adoc

@@ -14,6 +14,7 @@
 ** xref:concepts/long-task-timers.adoc[Long Task Timers]
 ** xref:concepts/histogram-quantiles.adoc[Histograms and Percentiles]
 ** xref:concepts/meter-provider.adoc[Meter Provider]
+** xref:concepts/meter-convention.adoc[Meter Convention]
 * xref:implementations.adoc[Implementations]
 ** xref:implementations/appOptics.adoc[AppOptics]
 ** xref:implementations/atlas.adoc[Atlas]

docs/modules/ROOT/pages/concepts/meter-convention.adoc

@@ -0,0 +1,7 @@
+[[meter-convention]]
+= Meter Convention
+
+While `MeterFilter` can be used to customize the name and tags (collectively, the convention) of Meters in any instrumentation, it can be more convenient and robust to customize the convention for a common instrumentation more directly.
+This is the purpose of the `MeterConvention`.
+
+For examples of its usage in instrumentation provided by Micrometer as well as examples of different implementations of a convention for an instrumentation, see the xref:../reference/jvm.adoc#meter-conventions[JVM metrics].

docs/modules/ROOT/pages/reference/jvm.adoc

@@ -52,6 +52,30 @@ To use the following `ExecutorService` instances, `--add-opens java.base/java.ut
 * `Executors.newThreadPerTaskExecutor()`
 * `Executors.newVirtualThreadPerTaskExecutor()`
 
+[[meter-conventions]]
+== Meter Conventions
+
+See also the general xref:../concepts/meter-convention.adoc[Meter Conventions] documentation.
+
+The following `MeterBinder` implementations have a constructor to customize the convention used for some or all of the meters they produce.
+This can be used as an alternative to customizing the Meter names and tags with a `MeterFilter`.
+
+* `ClassLoaderMetrics`
+* `JvmMemoryMetrics`
+* `JvmThreadMetrics`
+* `ProcessorMetrics`
+
+=== OpenTelemetry Semantic Conventions
+
+We provide `MeterConvention` implementations of the applicable https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/[OpenTelemetry semantic conventions for JVM metrics] that have been marked stable as of the version 1.37.0.
+These can be passed to the constructors of the above binders to change the convention from the default.
+Use the following classes:
+
+* `OpenTelemetryJvmClassLoadingMeterConventions`
+* `OpenTelemetryJvmMemoryMeterConventions`
+* `OpenTelemetryJvmThreadMeterConventions`
+* `OpenTelemetryJvmCpuMeterConventions`
+
 == Java 21 Metrics
 
 === Virtual Threads

micrometer-core/src/main/java/io/micrometer/core/instrument/binder/MeterConvention.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2025 VMware, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micrometer.core.instrument.binder;
+
+import io.micrometer.core.instrument.Meter;
+import io.micrometer.core.instrument.Tags;
+import io.micrometer.core.instrument.config.NamingConvention;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Convention describing a {@link Meter} used for a specific instrumentation. Different
+ * implementations of this convention may change the convention used by the same
+ * instrumentation logic. If the instrumentation is timing an operation, consider using
+ * the {@link Observation} API and {@link ObservationConvention} instead.
+ * {@link MeterConvention} is for instrumentation that is instrumented directly with the
+ * metrics API.
+ * <p>
+ * This is a distinct concept from {@link NamingConvention}. The name provided by the
+ * {@link MeterConvention} is the canonical name, which will potentially be transformed by
+ * a {@link NamingConvention} for a specific metrics backend or format.
+ *
+ * @param <C> context type used to derive tags
+ * @since 1.16.0
+ */
+// Work around NullAway. C might be Void, and thus we pass null to getTags.
+@NullUnmarked
+public interface MeterConvention<C extends @Nullable Object> {
+
+    /**
+     * Canonical name of the meter.
+     * @return meter name
+     */
+    @NonNull String getName();
+
+    /**
+     * Tags specific to this meter convention. Generally they should be combined with any
+     * common tags if this convention is associated with other conventions that share
+     * tags.
+     * @param context optional context which may be used for deriving tags
+     * @return tags instance to use with the meter described by this convention
+     */
+    default @NonNull Tags getTags(C context) {
+        return Tags.empty();
+    }
+
+}

micrometer-core/src/main/java/io/micrometer/core/instrument/binder/SimpleMeterConvention.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2025 VMware, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micrometer.core.instrument.binder;
+
+import io.micrometer.core.instrument.Tags;
+import org.jspecify.annotations.Nullable;
+
+import java.util.Objects;
+import java.util.function.Function;
+
+/**
+ * Basic implementation of a {@link MeterConvention}.
+ *
+ * @param <C> context type from which tags can be derived
+ * @since 1.16.0
+ */
+public class SimpleMeterConvention<C extends @Nullable Object> implements MeterConvention<C> {
+
+    private final String name;
+
+    private final @Nullable Tags tags;
+
+    private final @Nullable Function<C, Tags> tagsFunction;
+
+    /**
+     * Create a convention with a name and no tags.
+     * @param name meter name
+     */
+    public SimpleMeterConvention(String name) {
+        this(name, Tags.empty());
+    }
+
+    /**
+     * Create a convention with a name and fixed tags.
+     * @param name meter name
+     * @param tags tags associated with the meter
+     */
+    public SimpleMeterConvention(String name, Tags tags) {
+        this.name = name;
+        this.tags = tags;
+        this.tagsFunction = null;
+    }
+
+    /**
+     * Create a convention with a name and tags derived from a function.
+     * @param name meter name
+     * @param tagsFunction derive tags from the context with this function
+     */
+    public SimpleMeterConvention(String name, Function<C, Tags> tagsFunction) {
+        this.name = name;
+        this.tags = null;
+        this.tagsFunction = Objects.requireNonNull(tagsFunction);
+    }
+
+    @Override
+    public String getName() {
+        return name;
+    }
+
+    @Override
+    public Tags getTags(C context) {
+        return tags == null ? Objects.requireNonNull(tagsFunction).apply(context) : tags;
+    }
+
+}

micrometer-core/src/main/java/io/micrometer/core/instrument/binder/jvm/ClassLoaderMetrics.java

@@ -15,47 +15,75 @@
  */
 package io.micrometer.core.instrument.binder.jvm;
 
-import io.micrometer.core.instrument.FunctionCounter;
-import io.micrometer.core.instrument.Gauge;
-import io.micrometer.core.instrument.MeterRegistry;
-import io.micrometer.core.instrument.Tag;
+import io.micrometer.core.instrument.*;
 import io.micrometer.core.instrument.binder.BaseUnits;
 import io.micrometer.core.instrument.binder.MeterBinder;
-import org.jspecify.annotations.NullMarked;
+import io.micrometer.core.instrument.binder.MeterConvention;
+import io.micrometer.core.instrument.binder.jvm.convention.JvmClassLoadingMeterConventions;
+import io.micrometer.core.instrument.binder.jvm.convention.micrometer.MicrometerJvmClassLoadingMeterConventions;
 
 import java.lang.management.ClassLoadingMXBean;
 import java.lang.management.ManagementFactory;
 
-import static java.util.Collections.emptyList;
-
-@NullMarked
+/**
+ * Binder providing metrics related to JVM class loading.
+ *
+ * @see ClassLoadingMXBean
+ */
 public class ClassLoaderMetrics implements MeterBinder {
 
-    private final Iterable<Tag> tags;
+    private final JvmClassLoadingMeterConventions conventions;
 
+    /**
+     * Class loader metrics with the default convention.
+     */
     public ClassLoaderMetrics() {
-        this(emptyList());
+        this(new MicrometerJvmClassLoadingMeterConventions());
+    }
+
+    /**
+     * Class loader metrics using the default convention with extra tags added.
+     * @param extraTags additional tags to add to metrics registered by this binder
+     */
+    public ClassLoaderMetrics(Iterable<Tag> extraTags) {
+        this(new MicrometerJvmClassLoadingMeterConventions(Tags.of(extraTags)));
     }
 
-    public ClassLoaderMetrics(Iterable<Tag> tags) {
-        this.tags = tags;
+    /**
+     * Class loader metrics registered by this binder will use the provided convention.
+     * @param conventions custom convention to apply
+     * @since 1.16.0
+     */
+    public ClassLoaderMetrics(JvmClassLoadingMeterConventions conventions) {
+        this.conventions = conventions;
     }
 
     @Override
     public void bindTo(MeterRegistry registry) {
         ClassLoadingMXBean classLoadingBean = ManagementFactory.getClassLoadingMXBean();
 
-        Gauge.builder("jvm.classes.loaded", classLoadingBean, ClassLoadingMXBean::getLoadedClassCount)
-            .tags(tags)
+        MeterConvention<Object> currentClassCountConvention = conventions.currentClassCountConvention();
+        Gauge.builder(currentClassCountConvention.getName(), classLoadingBean, ClassLoadingMXBean::getLoadedClassCount)
+            .tags(currentClassCountConvention.getTags(null))
             .description("The number of classes that are currently loaded in the Java virtual machine")
             .baseUnit(BaseUnits.CLASSES)
             .register(registry);
 
-        FunctionCounter.builder("jvm.classes.unloaded", classLoadingBean, ClassLoadingMXBean::getUnloadedClassCount)
-            .tags(tags)
+        MeterConvention<Object> unloadedConvention = conventions.unloadedConvention();
+        FunctionCounter
+            .builder(unloadedConvention.getName(), classLoadingBean, ClassLoadingMXBean::getUnloadedClassCount)
+            .tags(unloadedConvention.getTags(null))
             .description("The number of classes unloaded in the Java virtual machine")
             .baseUnit(BaseUnits.CLASSES)
             .register(registry);
+
+        MeterConvention<Object> loadedConvention = conventions.loadedConvention();
+        FunctionCounter
+            .builder(loadedConvention.getName(), classLoadingBean, ClassLoadingMXBean::getTotalLoadedClassCount)
+            .tags(loadedConvention.getTags(null))
+            .description("The number of classes loaded in the Java virtual machine")
+            .baseUnit(BaseUnits.CLASSES)
+            .register(registry);
     }
 
 }

micrometer-core/src/main/java/io/micrometer/core/instrument/binder/jvm/JvmMemoryMetrics.java

@@ -21,12 +21,13 @@
 import io.micrometer.core.instrument.Tags;
 import io.micrometer.core.instrument.binder.BaseUnits;
 import io.micrometer.core.instrument.binder.MeterBinder;
-import org.jspecify.annotations.NullMarked;
+import io.micrometer.core.instrument.binder.MeterConvention;
+import io.micrometer.core.instrument.binder.jvm.convention.JvmMemoryMeterConventions;
+import io.micrometer.core.instrument.binder.jvm.convention.micrometer.MicrometerJvmMemoryMeterConventions;
 
 import java.lang.management.*;
 
 import static io.micrometer.core.instrument.binder.jvm.JvmMemory.getUsageValue;
-import static java.util.Collections.emptyList;
 
 /**
  * Record metrics that report utilization of various memory and buffer pools.
@@ -36,17 +37,36 @@
  * @see MemoryPoolMXBean
  * @see BufferPoolMXBean
  */
-@NullMarked
 public class JvmMemoryMetrics implements MeterBinder {
 
-    private final Iterable<Tag> tags;
+    private final Tags tags;
+
+    private final JvmMemoryMeterConventions conventions;
 
     public JvmMemoryMetrics() {
-        this(emptyList());
+        this(Tags.empty(), new MicrometerJvmMemoryMeterConventions());
+    }
+
+    /**
+     * Uses the default convention with the provided extra tags.
+     * @param extraTags tags to add to each meter's tags produced by this binder
+     */
+    public JvmMemoryMetrics(Iterable<Tag> extraTags) {
+        this(extraTags, new MicrometerJvmMemoryMeterConventions(Tags.of(extraTags)));
     }
 
-    public JvmMemoryMetrics(Iterable<Tag> tags) {
-        this.tags = tags;
+    /**
+     * Memory metrics with extra tags and a specific convention applied to meters. The
+     * supplied extra tags are not combined with the convention. Provide a convention that
+     * applies the extra tags if that is the desired outcome. The convention only applies
+     * to some meters.
+     * @param extraTags these will be added to meters not covered by the convention
+     * @param conventions custom conventions for applicable metrics
+     * @since 1.16.0
+     */
+    public JvmMemoryMetrics(Iterable<? extends Tag> extraTags, JvmMemoryMeterConventions conventions) {
+        this.tags = Tags.of(extraTags);
+        this.conventions = conventions;
     }
 
     @Override
@@ -74,24 +94,29 @@ public void bindTo(MeterRegistry registry) {
         }
 
         for (MemoryPoolMXBean memoryPoolBean : ManagementFactory.getPlatformMXBeans(MemoryPoolMXBean.class)) {
-            String area = MemoryType.HEAP.equals(memoryPoolBean.getType()) ? "heap" : "nonheap";
-            Iterable<Tag> tagsWithId = Tags.concat(tags, "id", memoryPoolBean.getName(), "area", area);
-
-            Gauge.builder("jvm.memory.used", memoryPoolBean, (mem) -> getUsageValue(mem, MemoryUsage::getUsed))
-                .tags(tagsWithId)
+            MeterConvention<MemoryPoolMXBean> memoryUsedConvention = conventions.getMemoryUsedConvention();
+            Gauge
+                .builder(memoryUsedConvention.getName(), memoryPoolBean,
+                        (mem) -> getUsageValue(mem, MemoryUsage::getUsed))
+                .tags(memoryUsedConvention.getTags(memoryPoolBean))
                 .description("The amount of used memory")
                 .baseUnit(BaseUnits.BYTES)
                 .register(registry);
 
+            MeterConvention<MemoryPoolMXBean> memoryCommittedConvention = conventions.getMemoryCommittedConvention();
             Gauge
-                .builder("jvm.memory.committed", memoryPoolBean, (mem) -> getUsageValue(mem, MemoryUsage::getCommitted))
-                .tags(tagsWithId)
+                .builder(memoryCommittedConvention.getName(), memoryPoolBean,
+                        (mem) -> getUsageValue(mem, MemoryUsage::getCommitted))
+                .tags(memoryCommittedConvention.getTags(memoryPoolBean))
                 .description("The amount of memory in bytes that is committed for the Java virtual machine to use")
                 .baseUnit(BaseUnits.BYTES)
                 .register(registry);
 
-            Gauge.builder("jvm.memory.max", memoryPoolBean, (mem) -> getUsageValue(mem, MemoryUsage::getMax))
-                .tags(tagsWithId)
+            MeterConvention<MemoryPoolMXBean> memoryMaxConvention = conventions.getMemoryMaxConvention();
+            Gauge
+                .builder(memoryMaxConvention.getName(), memoryPoolBean,
+                        (mem) -> getUsageValue(mem, MemoryUsage::getMax))
+                .tags(memoryMaxConvention.getTags(memoryPoolBean))
                 .description("The maximum amount of memory in bytes that can be used for memory management")
                 .baseUnit(BaseUnits.BYTES)
                 .register(registry);