Fixing the issue with always null logger in AttributeValueExtractor.

Renaming module 'jmx' to 'jmx-metrics'.
Changing the syntax of the metric attributes retrieved from Mbean attributes.
Editing docs and comments for better readability.

instrumentation/jmx/javaagent/README.md → instrumentation/jmx-metrics/javaagent/README.md

@@ -96,7 +96,7 @@ rules:
  - bean: java.lang:name=*,type=MemoryPool
  label:
  pool: param(name)
- type: attrib(Type)
+ type: attr(Type)
  mapping:
  Usage.used:
  metric: my.own.jvm.memory.pool.used
@@ -110,7 +110,7 @@ rules:
  unit: By
 ```
 
-The ObjectName pattern will match a number of MBeans, each for a different memory pool. The number and names of available memory pools, however, will be known only at runtime. To report values for all actual memory pools using only two metrics, we use metric attributes (referenced by the configuration file as `label`s). The first metric attribute, named `pool` will have its value derived from the ObjectName parameter `name` - which corresponds to the memory pool name. The second metric attribute, named `type` will get its value from the corresponding MBean attribute named `Type`. The values of this attribute are strings `HEAP` or `NON_HEAP` classifying the corresponding memory pool. Here the definition of the metric attributes is shared by both metrics, but it is also possible to define them at the individual metric level.
+The ObjectName pattern will match a number of MBeans, each for a different memory pool. The number and names of available memory pools, however, will be known only at runtime. To report values for all actual memory pools using only two metrics, we use metric attributes (referenced by the configuration file as `label` elements). The first metric attribute, named `pool` will have its value derived from the ObjectName parameter `name` - which corresponds to the memory pool name. The second metric attribute, named `type` will get its value from the corresponding MBean attribute named `Type`. The values of this attribute are strings `HEAP` or `NON_HEAP` classifying the corresponding memory pool. Here the definition of the metric attributes is shared by both metrics, but it is also possible to define them at the individual metric level.
 
 Using the above rule, when running on HotSpot JVM for Java 11, the following combinations of metric attributes will be reported.
  - {pool="Compressed Class Space", type="NON_HEAP"}
@@ -154,7 +154,7 @@ The referenced MBean has two attributes of interest, `bytesReceived`, and `bytes
 Keep in mind that when defining a metric multiple times like this, its type, unit and description must be exactly the same. Otherwise there will be complaints about attempts to redefine a metric in a non-compatible way.
 The example also demonstrates that when specifying a number of MBean attribute mappings within the same rule, the metric type can be declared only once (outside of the `mapping` section).
 
-Even when not reusing the metric name, special care also has to be taken when using ObjectName patterns (or specifying multiple ObjectNames). Different ObjectNames matching the pattern must result in using different metric attributes. Otherwise the same metric will be reported multiple times (using different values), which will likely clobber the previous values.
+Even when not reusing the metric name, special care also has to be taken when using ObjectName patterns (or specifying multiple ObjectNames - see the General Syntax section at the bottom of the page). Different ObjectNames matching the pattern must result in using different metric attributes. Otherwise the same metric will be reported multiple times (using different values), which will likely clobber the previous values.
 
 ### Making shortcuts
 
@@ -211,7 +211,7 @@ Thus, the above definitions will create several metrics, named `my.kafka.streams
 
 The metric descriptions will remain undefined, unless they are provided by the queried MBeans.
 
-### General syntax
+### General Syntax
 
 Here is the general description of the accepted configuration file syntax. The whole contents of the file is case-sensitive, with exception for `type` as described in the table below.
 
@@ -221,7 +221,7 @@ rules: # start of list of configuration rules
  - bean: <OBJECTNAME> # can contain wildcards
  label: # optional metric attributes, they apply to all metrics below
  <LABEL1>: param(<PARAM>) # <PARAM> is used as the key to extract value from actual ObjectName
- <LABEL2>: attrib(<ATTRIB>) # <ATTRIB> is used as the attribute name to extract value from MBean
+ <LABEL2>: attr(<ATTR>)  # <ATTR> is used as the attribute name to extract value from MBean
  prefix: <METRIC_NAME_PREFIX> # optional, useful for avoiding specifying metric names below
  unit: <UNIT> # optional, redefines the default unit for the whole rule
  type: <TYPE> # optional, redefines the default type for the whole rule
@@ -251,9 +251,9 @@ The following table explains the used terms with more details.
 
 | Syntactic Element | Description |
 | ---------------- | --------------- |
-| OBJECTNAME | A syntactically valid string representing an ObjectName (see [ObjectName constructor](https://docs.oracle.com/javase/8/docs/api/javax/management/ObjectName.html#ObjectName-java.lang.String-) ). |
+| OBJECTNAME | A syntactically valid string representing an ObjectName (see [ObjectName constructor](https://docs.oracle.com/javase/8/docs/api/javax/management/ObjectName.html#ObjectName-java.lang.String-)). |
 | LABEL | Any well-formed string that can be used as a metric [attribute](https://opentelemetry.io/docs/reference/specification/common/#attribute) key. |
-| ATTRIB | A non-empty string used as a name of the MBean attribute. The attribute value must be a String, otherwise the specified label (metric attribute) will not be used. |
+| ATTR | A non-empty string used as a name of the MBean attribute. The attribute value must be a String, otherwise the specified label (metric attribute) will not be used. |
 | PARAM | A non-empty string used as a property key for the ObjectName identifying the MBean which provides the metric value. If the ObjectName does not have a property with the given key, the specified label will not be used. |
 | METRIC_NAME_PREFIX | Any non-empty string which will be prepended to the specified metric (instrument) names. |
 | METRIC_NAME | Any non-empty string. The string, prefixed by the optional prefix (see above) must satisfy [instrument naming rule](https://opentelemetry.io/docs/reference/specification/metrics/api/#instrument-naming-rule). |
@@ -267,6 +267,6 @@ The following table explains the used terms with more details.
 
 This version of JMX Metric Insight has a number of limitations.
 
-- Attributes with the same name but belonging to different MBeans described by a single metric rule must have the same type (long or double).
+- MBean attributes with the same name but belonging to different MBeans described by a single metric rule must have the same type (long or double).
 - All MBeans which are described by the specified ObjectNames in a single rule must be registered with the same MBeanServer instance.
 - While MBeanServers and MBeans can be created dynamically by the application, it is assumed that they will live indefinitely. Their disappearance may not be recognized properly, and may lead to some memory leaks.

instrumentation/jmx-metrics/javaagent/build.gradle.kts

@@ -0,0 +1,10 @@
+plugins {
+ id("otel.javaagent-instrumentation")
+}
+
+dependencies {
+ implementation(project(":instrumentation:jmx-metrics:jmx-engine:library"))
+ implementation(project(":instrumentation:jmx-metrics:jmx-yaml:library"))
+
+ compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
+}

instrumentation/jmx/jmx-engine/library/src/main/java/io/opentelemetry/instrumentation/jmx/engine/AttributeValueExtractor.java → instrumentation/jmx-metrics/jmx-engine/library/src/main/java/io/opentelemetry/instrumentation/jmx/engine/AttributeValueExtractor.java

@@ -113,7 +113,7 @@ AttributeInfo getAttributeInfo(MBeanServer server, ObjectName objectName) {
 
  // Verify correctness of configuration by attempting to extract the metric value.
  // The value will be discarded, but its type will be checked.
- Object sampleValue = extractAttributeValue(server, objectName);
+ Object sampleValue = extractAttributeValue(server, objectName, logger);
 
  // Only numbers can be used to generate metric values
  if (sampleValue instanceof Number) {
@@ -162,7 +162,10 @@ AttributeInfo getAttributeInfo(MBeanServer server, ObjectName objectName) {
  *
  * @param server the MBeanServer to use
  * @param objectName the ObjectName specifying the MBean to use, it should not be a pattern
- * @param logger the logger to use, may be null
+ * @param logger the logger to use, may be null. Typically we want to log any issues with the
+ * attributes during MBean discovery, but once the attribute is successfuly detected and
+ * confirmed to be eligble for metric evaluation, any further attribute extraction
+ * malfunctions will be silent to avoid flooding the log.
  * @return the attribute value, if found, or null if an error occurred
  */
  private Object extractAttributeValue(MBeanServer server, ObjectName objectName, Logger logger) {

instrumentation/jmx/jmx-yaml/library/build.gradle.kts → instrumentation/jmx-metrics/jmx-yaml/library/build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 
 dependencies {
  implementation("org.yaml:snakeyaml")
- implementation(project(":instrumentation:jmx:jmx-engine:library"))
+ implementation(project(":instrumentation:jmx-metrics:jmx-engine:library"))
 
  testImplementation(project(":testing-common"))
 }

instrumentation/jmx/jmx-yaml/library/src/main/java/io/opentelemetry/instrumentation/jmx/yaml/MetricStructure.java → instrumentation/jmx-metrics/jmx-yaml/library/src/main/java/io/opentelemetry/instrumentation/jmx/yaml/MetricStructure.java

@@ -107,7 +107,7 @@ private static void addLabels(List<MetricLabel> list, Map<String, String> tagMap
  private static MetricLabel buildLabel(String key, String target) {
  // The recognized forms of target are:
  // - param(STRING)
- // - attrib(STRING)
+ // - attr(STRING)
  // - STRING
  // where STRING is the name of the corresponding parameter key, attribute name,
  // or the direct value to use
@@ -118,9 +118,9 @@ private static MetricLabel buildLabel(String key, String target) {
  if (k > 0) {
  return new MetricLabel(key, MetricLabel.fromParameter(target.substring(6, k).trim()));
  }
- } else if (target.startsWith("attrib(")) {
+ } else if (target.startsWith("attr(")) {
  if (k > 0) {
- return new MetricLabel(key, MetricLabel.fromAttribute(target.substring(7, k).trim()));
+ return new MetricLabel(key, MetricLabel.fromAttribute(target.substring(5, k).trim()));
  }
  } else if (k < 0) {
  return new MetricLabel(key, MetricLabel.fromConstant(target));

instrumentation/jmx/jmx-yaml/library/src/test/java/io/opentelemetry/instrumentation/jmx/engine/RuleParserTest.java → instrumentation/jmx-metrics/jmx-yaml/library/src/test/java/io/opentelemetry/instrumentation/jmx/engine/RuleParserTest.java

@@ -44,7 +44,7 @@ static void setup() throws Exception {
  + " - OBJECT:NAME2=*\n"
  + " label:\n"
  + " LABEL_KEY1: param(PARAMETER)\n"
- + " LABEL_KEY2: attrib(ATTRIBUTE)\n"
+ + " LABEL_KEY2: attr(ATTRIBUTE)\n"
  + " prefix: METRIC_NAME_PREFIX\n"
  + " mapping:\n"
  + " ATTRIBUTE1:\n"
@@ -133,7 +133,7 @@ void testConf3() throws Exception {
  + " - bean: my-test:type=4\n"
  + " label:\n"
  + " LABEL_KEY1: param(PARAMETER)\n"
- + " LABEL_KEY2: attrib(ATTRIBUTE)\n"
+ + " LABEL_KEY2: attr(ATTRIBUTE)\n"
  + " prefix: PREFIX.\n"
  + " type: upDownCounter\n"
  + " unit: DEFAULT_UNIT\n"
@@ -363,7 +363,7 @@ void testInvalidTag() throws Exception {
  + " mapping:\n"
  + " ATTRIB:\n"
  + " label:\n"
- + " LABEL: attr(something)\n"
+ + " LABEL: attrib(something)\n"
  + " metric: METRIC_NAME\n";
  runNegativeTest(yaml);
  }
@@ -390,7 +390,7 @@ void testInvalidTagFromAttribute() throws Exception {
  + " mapping:\n"
  + " ATTRIB:\n"
  + " label:\n"
- + " LABEL: attrib(.used)\n"
+ + " LABEL: attr(.used)\n"
  + " metric: METRIC_NAME\n";
  runNegativeTest(yaml);
  }
@@ -404,7 +404,7 @@ void testEmptyTagFromAttribute() throws Exception {
  + " mapping:\n"
  + " ATTRIB:\n"
  + " label:\n"
- + " LABEL: attrib( )\n"
+ + " LABEL: attr( )\n"
  + " metric: METRIC_NAME\n";
  runNegativeTest(yaml);
  }

settings.gradle.kts

@@ -298,9 +298,9 @@ include(":instrumentation:jetty-httpclient:jetty-httpclient-9.2:library")
 include(":instrumentation:jetty-httpclient:jetty-httpclient-9.2:testing")
 include(":instrumentation:jms-1.1:javaagent")
 include(":instrumentation:jms-1.1:javaagent-unit-tests")
-include(":instrumentation:jmx:javaagent")
-include(":instrumentation:jmx:jmx-engine:library")
-include(":instrumentation:jmx:jmx-yaml:library")
+include(":instrumentation:jmx-metrics:javaagent")
+include(":instrumentation:jmx-metrics:jmx-engine:library")
+include(":instrumentation:jmx-metrics:jmx-yaml:library")
 include(":instrumentation:jsf:jsf-common:javaagent")
 include(":instrumentation:jsf:jsf-common:testing")
 include(":instrumentation:jsf:jsf-mojarra-1.2:javaagent")