jmx move to internal package + deprecate old API (#15658)

SylvainJuge · web-flow · commit e30ad972e8b4 · 2025-12-19T12:51:34.000-08:00
diff --git a/instrumentation/jmx-metrics/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/jmx/JmxMetricInsightInstallerTest.java b/instrumentation/jmx-metrics/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/jmx/JmxMetricInsightInstallerTest.java
@@ -9,7 +9,7 @@
 
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.instrumentation.jmx.JmxTelemetry;
-import io.opentelemetry.instrumentation.jmx.yaml.RuleParser;
+import io.opentelemetry.instrumentation.jmx.internal.yaml.RuleParser;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.Arrays;
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/JmxTelemetry.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/JmxTelemetry.java
@@ -7,8 +7,8 @@
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import io.opentelemetry.api.OpenTelemetry;
-import io.opentelemetry.instrumentation.jmx.engine.JmxMetricInsight;
-import io.opentelemetry.instrumentation.jmx.engine.MetricConfiguration;
+import io.opentelemetry.instrumentation.jmx.internal.engine.JmxMetricInsight;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricConfiguration;
 import java.util.List;
 import java.util.function.Supplier;
 import javax.management.MBeanServerConnection;
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/JmxTelemetryBuilder.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/JmxTelemetryBuilder.java
@@ -9,8 +9,8 @@
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import io.opentelemetry.api.OpenTelemetry;
-import io.opentelemetry.instrumentation.jmx.engine.MetricConfiguration;
-import io.opentelemetry.instrumentation.jmx.yaml.RuleParser;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricConfiguration;
+import io.opentelemetry.instrumentation.jmx.internal.yaml.RuleParser;
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.file.Files;
@@ -54,8 +54,9 @@ public JmxTelemetryBuilder beanDiscoveryDelay(Duration delay) {
    * @param target name of target in /jmx/rules/{target}.yaml classpath resource
    * @return builder instance
    * @throws IllegalArgumentException when classpath resource does not exist or can't be parsed
+   * @deprecated use {@link #addRules(InputStream)} instead
    */
-  // TODO: deprecate this method after 2.23.0 release in favor of addRules
+  @Deprecated
   @CanIgnoreReturnValue
   public JmxTelemetryBuilder addClassPathRules(String target) {
     String resourcePath = String.format("jmx/rules/%s.yaml", target);
@@ -111,8 +112,9 @@ public JmxTelemetryBuilder addRules(Path path) {
    * @param path path to yaml file
    * @return builder instance
    * @throws IllegalArgumentException when classpath resource does not exist or can't be parsed
+   * @deprecated use {@link #addRules(Path)} instead
    */
-  // TODO: deprecate this method after 2.23.0 release in favor of addRules
+  @Deprecated
   @CanIgnoreReturnValue
   public JmxTelemetryBuilder addCustomRules(Path path) {
     return addRules(path);
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/AttributeInfo.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/AttributeInfo.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import javax.annotation.Nullable;
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/BeanAttributeExtractor.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/BeanAttributeExtractor.java
@@ -3,12 +3,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import static java.util.logging.Level.FINE;
 import static java.util.logging.Level.INFO;
 
-import io.opentelemetry.instrumentation.jmx.yaml.StateMapping;
+import io.opentelemetry.instrumentation.jmx.internal.yaml.StateMapping;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.logging.Level;
@@ -25,6 +25,9 @@
 /**
  * A class responsible for extracting attribute values from MBeans. Objects of this class are
  * immutable.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class BeanAttributeExtractor implements MetricAttributeExtractor {
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/BeanFinder.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/BeanFinder.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import java.io.IOException;
 import java.lang.management.ManagementFactory;
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/BeanGroup.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/BeanGroup.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -15,6 +15,9 @@
 /**
  * A class describing a set of MBeans which can be used to collect values for a metric. Objects of
  * this class are immutable.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class BeanGroup {
   // How to specify the MBean(s)
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/DetectionStatus.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/DetectionStatus.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import java.util.Collection;
 import javax.management.MBeanServerConnection;
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/JmxMetricInsight.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/JmxMetricInsight.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import static java.util.logging.Level.FINE;
 
@@ -14,7 +14,12 @@
 import javax.management.MBeanServerConnection;
 import javax.management.MBeanServerFactory;
 
-/** Collecting and exporting JMX metrics. */
+/**
+ * Collecting and exporting JMX metrics.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
 public class JmxMetricInsight {
 
   private static final Logger logger = Logger.getLogger(JmxMetricInsight.class.getName());
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricAttribute.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricAttribute.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import javax.annotation.Nullable;
 import javax.management.MBeanServerConnection;
@@ -13,6 +13,9 @@
  * A class representing a metric attribute. It is responsible for extracting the attribute value (to
  * be reported as a Measurement attribute), and for holding the corresponding attribute name to be
  * used. Objects of this class are immutable.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class MetricAttribute {
   private final String name;
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricAttributeExtractor.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricAttributeExtractor.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import java.util.Locale;
 import javax.annotation.Nullable;
@@ -13,6 +13,9 @@
 /**
  * MetricAttributeExtractors are responsible for obtaining values for populating metric attributes,
  * i.e. measurement attributes.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public interface MetricAttributeExtractor {
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricConfiguration.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricConfiguration.java
@@ -3,13 +3,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import java.util.ArrayList;
 import java.util.Collection;
 
 /**
  * A class responsible for maintaining the current configuration for JMX metrics to be collected.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class MetricConfiguration {
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricDef.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricDef.java
@@ -3,14 +3,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import java.util.List;
 
 /**
  * A class providing a complete definition on how to create an OpenTelemetry metric out of the JMX
  * system: how to extract values from MBeans and how to model, name and decorate them with
  * attributes using OpenTelemetry Metric API. Objects of this class are immutable.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 
 // Example: The rule described by the following YAML definition
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricExtractor.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricExtractor.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import java.util.List;
 import javax.annotation.Nullable;
@@ -14,6 +14,9 @@
  *
  * <p>Objects of this class are stateful, the DetectionStatus may change over time to keep track of
  * all ObjectNames that should be used to deliver the metric values.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class MetricExtractor {
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricInfo.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricInfo.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import javax.annotation.Nullable;
 
@@ -12,10 +12,18 @@
  * metric to be reported with OpenTelemetry.
  *
  * <p>Objects of this class are immutable.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class MetricInfo {
 
-  // OpenTelemetry asynchronous instrument types that can be used
+  /**
+   * OpenTelemetry asynchronous instrument types that can be used
+   *
+   * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+   * at any time.
+   */
   public enum Type {
     COUNTER,
     UPDOWNCOUNTER,
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricRegistrar.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricRegistrar.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import static java.util.logging.Level.INFO;
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/UnitConverter.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/engine/UnitConverter.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.engine;
+package io.opentelemetry.instrumentation.jmx.internal.engine;
 
 import java.util.HashMap;
 import java.util.Map;
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/JmxConfig.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/JmxConfig.java
@@ -3,15 +3,18 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.yaml;
+package io.opentelemetry.instrumentation.jmx.internal.yaml;
 
-import io.opentelemetry.instrumentation.jmx.engine.MetricConfiguration;
-import io.opentelemetry.instrumentation.jmx.engine.MetricDef;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricConfiguration;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricDef;
 import java.util.List;
 
 /**
  * JMX configuration as a set of JMX rules. Objects of this class are created and populated by the
  * YAML parser.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class JmxConfig {
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/JmxRule.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/JmxRule.java
@@ -3,16 +3,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.yaml;
+package io.opentelemetry.instrumentation.jmx.internal.yaml;
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
-import io.opentelemetry.instrumentation.jmx.engine.BeanAttributeExtractor;
-import io.opentelemetry.instrumentation.jmx.engine.BeanGroup;
-import io.opentelemetry.instrumentation.jmx.engine.MetricAttribute;
-import io.opentelemetry.instrumentation.jmx.engine.MetricAttributeExtractor;
-import io.opentelemetry.instrumentation.jmx.engine.MetricDef;
-import io.opentelemetry.instrumentation.jmx.engine.MetricExtractor;
-import io.opentelemetry.instrumentation.jmx.engine.MetricInfo;
+import io.opentelemetry.instrumentation.jmx.internal.engine.BeanAttributeExtractor;
+import io.opentelemetry.instrumentation.jmx.internal.engine.BeanGroup;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricAttribute;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricAttributeExtractor;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricDef;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricExtractor;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricInfo;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
@@ -25,6 +25,9 @@
 /**
  * This class represents a complete JMX metrics rule as defined by a YAML file. Objects of this
  * class are created and populated by the YAML parser.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class JmxRule extends MetricStructure {
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/Metric.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/Metric.java
@@ -3,15 +3,18 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.yaml;
+package io.opentelemetry.instrumentation.jmx.internal.yaml;
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
-import io.opentelemetry.instrumentation.jmx.engine.MetricInfo;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricInfo;
 import javax.annotation.Nullable;
 
 /**
  * A class representing metric definition as a part of YAML metric rule. Objects of this class are
  * created and populated by the YAML parser.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
 public class Metric extends MetricStructure {
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/MetricStructure.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/MetricStructure.java
@@ -3,12 +3,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.jmx.yaml;
+package io.opentelemetry.instrumentation.jmx.internal.yaml;
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
-import io.opentelemetry.instrumentation.jmx.engine.MetricAttribute;
-import io.opentelemetry.instrumentation.jmx.engine.MetricAttributeExtractor;
-import io.opentelemetry.instrumentation.jmx.engine.MetricInfo;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricAttribute;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricAttributeExtractor;
+import io.opentelemetry.instrumentation.jmx.internal.engine.MetricInfo;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
@@ -23,6 +23,9 @@
  * <li>the sourceUnit
  *
  *     <p>Known subclasses are {@link JmxRule} and {@link Metric}.
+ *
+ *     <p>This class is internal and is hence not for public use. Its APIs are unstable and can
+ *     change at any time.
  */
 public abstract class MetricStructure {
 
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/RuleParser.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/RuleParser.java
diff --git a/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/StateMapping.java b/instrumentation/jmx-metrics/library/src/main/java/io/opentelemetry/instrumentation/jmx/internal/yaml/StateMapping.java
diff --git a/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/engine/AttributeExtractorTest.java b/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/engine/AttributeExtractorTest.java
diff --git a/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricAggregationTest.java b/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/engine/MetricAggregationTest.java
diff --git a/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/engine/RuleParserTest.java b/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/engine/RuleParserTest.java
diff --git a/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/engine/UnitConverterTest.java b/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/engine/UnitConverterTest.java
diff --git a/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/yaml/MetricStructureTest.java b/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/yaml/MetricStructureTest.java
diff --git a/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/yaml/StateMappingTest.java b/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/internal/yaml/StateMappingTest.java
diff --git a/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/rules/TargetSystemTest.java b/instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/rules/TargetSystemTest.java
