jmx state metrics (#12369)

Co-authored-by: Jay DeLuca <jaydeluca4@gmail.com>

instrumentation/jmx-metrics/javaagent/README.md

@@ -221,6 +221,67 @@ 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.
 
+### State Metrics
+
+Some JMX attributes expose current state as a non-numeric MBean attribute, in order to capture those as metrics it is recommended to use the special `state` metric type.
+For example, with Tomcat connector, the `Catalina:type=Connector,port=*` MBean has `stateName` (of type `String`), we can define the following rule:
+
+```yaml
+---
+rules:
+ - bean: Catalina:type=Connector,port=*
+ mapping:
+ stateName:
+ type: state
+ metric: tomcat.connector
+ metricAttribute:
+ port: param(port)
+ connector_state:
+ ok: STARTED
+ failed: [STOPPED,FAILED]
+ degraded: '*'
+```
+
+For a given value of `port`, let's say `8080` This will capture the `tomcat.connector.state` metric of type `updowncounter` with value `0` or `1` and the `state` metric attribute will have a value in [`ok`,`failed`,`degraded`].
+For every sample, 3 metrics will be captured for each value of `state` depending on the value of `stateName`:
+
+When `stateName` = `STARTED`, we have:
+
+- `tomcat.connector` value = `1`, attributes `port` = `8080` and `connector_state` = `ok`
+- `tomcat.connector` value = `0`, attributes `port` = `8080` and `connector_state` = `failed`
+- `tomcat.connector` value = `0`, attributes `port` = `8080` and `connector_state` = `degraded`
+
+When `stateName` = `STOPPED` or `FAILED`, we have:
+
+- `tomcat.connector` value = `0`, attributes `port` = `8080` and `connector_state` = `ok`
+- `tomcat.connector` value = `1`, attributes `port` = `8080` and `connector_state` = `failed`
+- `tomcat.connector` value = `0`, attributes `port` = `8080` and `connector_state` = `degraded`
+
+For other values of `stateName`, we have:
+
+- `tomcat.connector` value = `0`, attributes `port` = `8080` and `connector_state` = `ok`
+- `tomcat.connector` value = `0`, attributes `port` = `8080` and `connector_state` = `failed`
+- `tomcat.connector` value = `1`, attributes `port` = `8080` and `connector_state` = `degraded`
+
+Each state key can be mapped to one or more values of the MBean attribute using:
+- a string literal or a string array
+- a `*` character to provide default option and avoid enumerating all values, this value must be quoted in YAML
+
+Exactly one `*` value must be present in the mapping to ensure all possible values of the MBean attribute can be mapped to a state key.
+
+The default value indicated by `*` does not require a dedicated state key. For example, if we want to have `connector_state` metric attribute with values `on` or `off`, we can use:
+```yaml
+ connector_state:
+ on: STARTED
+ off: [STOPPED,FAILED,'*']
+```
+In the particular case where only two values are defined, we can simplify further by explicitly defining one state and rely on default for the other.
+```yaml
+ connector_state:
+ on: STARTED
+ off: '*'
+```
+
 ### 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.

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

@@ -151,7 +151,7 @@ AttributeInfo getAttributeInfo(MBeanServerConnection connection, ObjectName obje
 
  // 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(connection, objectName, logger);
+ Object sampleValue = getSampleValue(connection, objectName);
 
  // Only numbers can be used to generate metric values
  if (sampleValue instanceof Number) {
@@ -194,6 +194,11 @@ AttributeInfo getAttributeInfo(MBeanServerConnection connection, ObjectName obje
  return null;
  }
 
+ @Nullable
+ protected Object getSampleValue(MBeanServerConnection connection, ObjectName objectName) {
+ return extractAttributeValue(connection, objectName, logger);
+ }
+
  /**
  * Extracts the specified attribute value. In case the value is a CompositeData, drills down into
  * it to find the correct singleton value (usually a Number or a String).
@@ -203,7 +208,7 @@ AttributeInfo getAttributeInfo(MBeanServerConnection connection, ObjectName obje
  * pattern
  * @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 successfully detected and
- * confirmed to be eligble for metric evaluation, any further attribute extraction
+ * confirmed to be eligible for metric evaluation, any further attribute extraction
  * malfunctions will be silent to avoid flooding the log.
  * @return the attribute value, if found, or {@literal null} if an error occurred
  */
@@ -253,7 +258,8 @@ private Object extractAttributeValue(MBeanServerConnection connection, ObjectNam
  }
 
  @Nullable
- Number extractNumericalAttribute(MBeanServerConnection connection, ObjectName objectName) {
+ protected Number extractNumericalAttribute(
+ MBeanServerConnection connection, ObjectName objectName) {
  Object value = extractAttributeValue(connection, objectName);
  if (value instanceof Number) {
  return (Number) value;

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

@@ -5,7 +5,11 @@
 
 package io.opentelemetry.instrumentation.jmx.engine;
 
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 import javax.annotation.Nullable;
+import javax.management.MalformedObjectNameException;
 import javax.management.ObjectName;
 import javax.management.QueryExp;
 
@@ -16,7 +20,7 @@
 public class BeanGroup {
  // How to specify the MBean(s)
  @Nullable private final QueryExp queryExp;
- private final ObjectName[] namePatterns;
+ private final List<ObjectName> namePatterns;
 
  /**
  * Constructor for BeanGroup.
@@ -25,17 +29,29 @@ public class BeanGroup {
  * @param namePatterns an array of ObjectNames used to look for MBeans; usually they will be
  * patterns. If multiple patterns are provided, they work as logical OR.
  */
- public BeanGroup(@Nullable QueryExp queryExp, ObjectName... namePatterns) {
+ private BeanGroup(@Nullable QueryExp queryExp, List<ObjectName> namePatterns) {
  this.queryExp = queryExp;
  this.namePatterns = namePatterns;
  }
 
+ public static BeanGroup forSingleBean(String bean) throws MalformedObjectNameException {
+ return new BeanGroup(null, Collections.singletonList(new ObjectName(bean)));
+ }
+
+ public static BeanGroup forBeans(List<String> beans) throws MalformedObjectNameException {
+ List<ObjectName> list = new ArrayList<>();
+ for (String name : beans) {
+ list.add(new ObjectName(name));
+ }
+ return new BeanGroup(null, list);
+ }
+
  @Nullable
  QueryExp getQueryExp() {
  return queryExp;
  }
 
- ObjectName[] getNamePatterns() {
+ List<ObjectName> getNamePatterns() {
  return namePatterns;
  }
 }

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

@@ -22,6 +22,10 @@ public MetricAttribute(String name, MetricAttributeExtractor extractor) {
  this.extractor = extractor;
  }
 
+ public boolean isStateAttribute() {
+ return extractor == null;
+ }
+
  public String getAttributeName() {
  return name;
  }

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

@@ -5,6 +5,8 @@
 
 package io.opentelemetry.instrumentation.jmx.engine;
 
+import java.util.List;
+
 /**
  * A class providing a complete definition on how to create an Open Telemetry metric out of the JMX
  * system: how to extract values from MBeans and how to model, name and decorate them with
@@ -74,7 +76,7 @@ public class MetricDef {
  private final BeanGroup beans;
 
  // Describes how to get the metric values and their attributes, and how to report them
- private final MetricExtractor[] metricExtractors;
+ private final List<MetricExtractor> metricExtractors;
 
  /**
  * Constructor for MetricDef.
@@ -84,7 +86,7 @@ public class MetricDef {
  * MetricExtractor is provided, they should use unique metric names or unique metric
  * attributes
  */
- public MetricDef(BeanGroup beans, MetricExtractor... metricExtractors) {
+ public MetricDef(BeanGroup beans, List<MetricExtractor> metricExtractors) {
  this.beans = beans;
  this.metricExtractors = metricExtractors;
  }
@@ -93,7 +95,7 @@ BeanGroup getBeanGroup() {
  return beans;
  }
 
- MetricExtractor[] getMetricExtractors() {
+ List<MetricExtractor> getMetricExtractors() {
  return metricExtractors;
  }
 }

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

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.instrumentation.jmx.engine;
 
+import java.util.List;
 import javax.annotation.Nullable;
 
 /**
@@ -22,14 +23,14 @@ public class MetricExtractor {
  private final BeanAttributeExtractor attributeExtractor;
 
  // Defines the Measurement attributes to be used when reporting the metric value.
- private final MetricAttribute[] attributes;
+ private final List<MetricAttribute> attributes;
 
  @Nullable private volatile DetectionStatus status;
 
  public MetricExtractor(
  BeanAttributeExtractor attributeExtractor,
  MetricInfo metricInfo,
- MetricAttribute... attributes) {
+ List<MetricAttribute> attributes) {
  this.attributeExtractor = attributeExtractor;
  this.metricInfo = metricInfo;
  this.attributes = attributes;
@@ -43,7 +44,7 @@ BeanAttributeExtractor getMetricValueExtractor() {
  return attributeExtractor;
  }
 
- MetricAttribute[] getAttributes() {
+ List<MetricAttribute> getAttributes() {
  return attributes;
  }
 

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

@@ -19,7 +19,9 @@ public class MetricInfo {
  public enum Type {
  COUNTER,
  UPDOWNCOUNTER,
- GAUGE
+ GAUGE,
+ /** state metric captured as updowncounter */
+ STATE
  }
 
  // How to report the metric using OpenTelemetry API
@@ -44,21 +46,21 @@ public MetricInfo(
  this.type = type == null ? Type.GAUGE : type;
  }
 
- String getMetricName() {
+ public String getMetricName() {
  return metricName;
  }
 
  @Nullable
- String getDescription() {
+ public String getDescription() {
  return description;
  }
 
  @Nullable
- String getUnit() {
+ public String getUnit() {
  return unit;
  }
 
- Type getType() {
+ public Type getType() {
  return type;
  }
 }

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

@@ -120,6 +120,13 @@ void enrollExtractor(
  }
  logger.log(INFO, "Created Gauge for {0}", metricName);
  }
+ break;
+ // CHECKSTYLE:OFF
+ case STATE:
+ {
+ // CHECKSTYLE:ON
+ throw new IllegalStateException("state metrics should not be registered");
+ }
  }
  }
 
@@ -173,9 +180,8 @@ static Consumer<ObservableLongMeasurement> longTypeCallback(MetricExtractor extr
  */
  static Attributes createMetricAttributes(
  MBeanServerConnection connection, ObjectName objectName, MetricExtractor extractor) {
- MetricAttribute[] metricAttributes = extractor.getAttributes();
  AttributesBuilder attrBuilder = Attributes.builder();
- for (MetricAttribute metricAttribute : metricAttributes) {
+ for (MetricAttribute metricAttribute : extractor.getAttributes()) {
  String attributeValue = metricAttribute.acquireAttributeValue(connection, objectName);
  if (attributeValue != null) {
  attrBuilder = attrBuilder.put(metricAttribute.getAttributeName(), attributeValue);