jmx state metrics

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/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/yaml/JmxRule.java

@@ -9,6 +9,7 @@
 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;
@@ -18,6 +19,7 @@
 import java.util.Map;
 import java.util.Set;
 import javax.annotation.Nullable;
+import javax.management.MBeanServerConnection;
 import javax.management.MalformedObjectNameException;
 import javax.management.ObjectName;
 
@@ -143,8 +145,7 @@ public MetricDef buildMetricDef() throws Exception {
     }
 
     Set<String> attrNames = mapping.keySet();
-    MetricExtractor[] metricExtractors = new MetricExtractor[attrNames.size()];
-    int n = 0;
+    List<MetricExtractor> metricExtractors = new ArrayList<>();
     for (String attributeName : attrNames) {
       BeanAttributeExtractor attrExtractor = BeanAttributeExtractor.fromName(attributeName);
       // This is essentially the same as 'attributeName' but with escape characters removed
@@ -162,44 +163,104 @@ public MetricDef buildMetricDef() throws Exception {
         metricInfo = m.buildMetricInfo(prefix, niceAttributeName, getUnit(), getMetricType());
       }
 
-      List<MetricAttribute> attributeList;
       List<MetricAttribute> ownAttributes = getAttributeList();
-      if (ownAttributes != null && m != null && m.getAttributeList() != null) {
-        // MetricAttributes have been specified at two levels, need to combine them
-        attributeList = combineMetricAttributes(ownAttributes, m.getAttributeList());
-      } else if (ownAttributes != null) {
-        attributeList = ownAttributes;
-      } else if (m != null && m.getAttributeList() != null) {
-        // Get the attributes from the metric
-        attributeList = m.getAttributeList();
+      List<MetricAttribute> metricAttributes = m != null ? m.getAttributeList() : null;
+      List<MetricAttribute> attributeList =
+          combineMetricAttributes(ownAttributes, metricAttributes);
+
+      // higher priority to metric level mapping, then jmx rule as fallback
+      StateMapping stateMapping = getEffectiveStateMapping(m, this);
+
+      if (stateMapping.isEmpty()) {
+        metricExtractors.add(
+            new MetricExtractor(
+                attrExtractor, metricInfo, attributeList.toArray(new MetricAttribute[0])));
       } else {
-        // There are no attributes at all
-        attributeList = new ArrayList<MetricAttribute>();
+
+        // generate one metric extractor per state metric key
+        // each metric extractor will have the state attribute replaced with a constant
+        metricExtractors.addAll(
+            createStateMappingExtractors(stateMapping, attributeList, attrExtractor, metricInfo));
       }
+    }
+
+    return new MetricDef(group, metricExtractors.toArray(new MetricExtractor[0]));
+  }
+
+  private static List<MetricExtractor> createStateMappingExtractors(
+      StateMapping stateMapping,
+      List<MetricAttribute> attributeList,
+      BeanAttributeExtractor attrExtractor,
+      MetricInfo metricInfo) {
+
+    List<MetricExtractor> extractors = new ArrayList<>();
+    for (String key : stateMapping.getStateKeys()) {
+      List<MetricAttribute> stateMetricAttributes = new ArrayList<>();
+
+      for (MetricAttribute ma : attributeList) {
+        // replace state metric attribute with constant key value
+        if (!ma.isStateAttribute()) {
+          stateMetricAttributes.add(ma);
+        } else {
+          stateMetricAttributes.add(
+              new MetricAttribute(
+                  ma.getAttributeName(), MetricAttributeExtractor.fromConstant(key)));
+        }
+      }
+
+      BeanAttributeExtractor stateMetricExtractor =
+          new BeanAttributeExtractor(attrExtractor.getAttributeName()) {
 
-      MetricExtractor metricExtractor =
+            @Override
+            protected Object getSampleValue(
+                MBeanServerConnection connection, ObjectName objectName) {
+              // metric actual type is sampled in the discovery process, so we have to
+              // make this extractor as extracting integers.
+              return 0;
+            }
+
+            @Override
+            protected Number extractNumericalAttribute(
+                MBeanServerConnection connection, ObjectName objectName) {
+              String rawStateValue = attrExtractor.extractValue(connection, objectName);
+              String mappedStateValue = stateMapping.getStateValue(rawStateValue);
+              return key.equals(mappedStateValue) ? 1 : 0;
+            }
+          };
+
+      extractors.add(
           new MetricExtractor(
-              attrExtractor,
+              stateMetricExtractor,
               metricInfo,
-              attributeList.toArray(new MetricAttribute[attributeList.size()]));
-      metricExtractors[n++] = metricExtractor;
+              stateMetricAttributes.toArray(new MetricAttribute[0])));
     }
-
-    return new MetricDef(group, metricExtractors);
+    return extractors;
   }
 
   private static List<MetricAttribute> combineMetricAttributes(
       List<MetricAttribute> ownAttributes, List<MetricAttribute> metricAttributes) {
+
     Map<String, MetricAttribute> set = new HashMap<>();
-    for (MetricAttribute ownAttribute : ownAttributes) {
-      set.put(ownAttribute.getAttributeName(), ownAttribute);
+    if (ownAttributes != null) {
+      for (MetricAttribute ownAttribute : ownAttributes) {
+        set.put(ownAttribute.getAttributeName(), ownAttribute);
+      }
     }
-
-    // Let the metric level defined attributes override own attributes
-    for (MetricAttribute metricAttribute : metricAttributes) {
-      set.put(metricAttribute.getAttributeName(), metricAttribute);
+    if (metricAttributes != null) {
+      // Let the metric level defined attributes override own attributes
+      for (MetricAttribute metricAttribute : metricAttributes) {
+        set.put(metricAttribute.getAttributeName(), metricAttribute);
+      }
     }
 
-    return new ArrayList<MetricAttribute>(set.values());
+    return new ArrayList<>(set.values());
+  }
+
+  private static StateMapping getEffectiveStateMapping(Metric m, JmxRule rule) {
+    if (m == null || m.getStateMapping().isEmpty()) {
+      return rule.getStateMapping();
+    } else {
+      return m.getStateMapping();
+    }
   }
 }

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

@@ -20,7 +20,7 @@
  * <li>the metric attributes
  * <li>the unit
  *
- *     <p>Known subclasses are JmxRule and Metric.
+ *     <p>Known subclasses are {@link JmxRule} and {@link Metric}.
  */
 abstract class MetricStructure {
 
@@ -30,14 +30,22 @@ abstract class MetricStructure {
   //      KEY1: SPECIFICATION1
   //      KEY2: SPECIFICATION2
   //    unit: UNIT
-
-  private Map<String, String> metricAttribute; // unused, for YAML parser only
+  //    stateMapping:
+  //      state1: [a,b]
+  //      state2: c
+  //      state3: '*'
+
+  private Map<String, String> metricAttribute;
+  private StateMapping stateMapping = StateMapping.empty();
+  private static final String STATE_MAPPING_WILDCARD = "*";
   private String unit;
 
   private MetricInfo.Type metricType;
   private List<MetricAttribute> metricAttributes;
 
-  public void setType(String t) {
+  MetricStructure() {}
+
+  void setType(String t) {
     // Do not complain about case variations
     t = t.trim().toUpperCase(Locale.ROOT);
     this.metricType = MetricInfo.Type.valueOf(t);
@@ -51,6 +59,36 @@ public void setUnit(String unit) {
     this.unit = validateUnit(unit.trim());
   }
 
+  void setStateMapping(Map<String, Object> stateMapping) {
+    StateMapping.Builder builder = StateMapping.builder();
+    for (Map.Entry<String, Object> entry : stateMapping.entrySet()) {
+      String stateKey = entry.getKey();
+      Object stateValue = entry.getValue();
+      if (stateValue instanceof String) {
+        addMappedValue(builder, (String) stateValue, stateKey);
+      } else if (stateValue instanceof List) {
+        for (Object listEntry : (List<?>) stateValue) {
+          if (!(listEntry instanceof String)) {
+            throw new IllegalArgumentException("unexpected state list value: " + stateKey);
+          }
+          addMappedValue(builder, (String) listEntry, stateKey);
+        }
+      } else {
+        throw new IllegalArgumentException("unexpected state value: " + stateValue);
+      }
+    }
+    this.stateMapping = builder.build();
+  }
+
+  private static void addMappedValue(
+      StateMapping.Builder builder, String stateValue, String stateKey) {
+    if (stateValue.equals(STATE_MAPPING_WILDCARD)) {
+      builder.withDefaultState(stateKey);
+    } else {
+      builder.withMappedValue(stateValue, stateKey);
+    }
+  }
+
   @CanIgnoreReturnValue
   private String validateUnit(String unit) {
     requireNonEmpty(unit, "Metric unit is empty");
@@ -67,9 +105,7 @@ private String validateUnit(String unit) {
   public void setMetricAttribute(Map<String, String> map) {
     this.metricAttribute = map;
     // pre-build the MetricAttributes
-    List<MetricAttribute> attrList = new ArrayList<>();
-    addMetricAttributes(attrList, map);
-    this.metricAttributes = attrList;
+    this.metricAttributes = addMetricAttributes(map);
   }
 
   // Used only for testing
@@ -91,47 +127,66 @@ protected void requireNonEmpty(String s, String msg) {
     }
   }
 
-  private static void addMetricAttributes(
-      List<MetricAttribute> list, Map<String, String> metricAttributeMap) {
-    if (metricAttributeMap != null) {
-      for (String key : metricAttributeMap.keySet()) {
-        String target = metricAttributeMap.get(key);
-        if (target == null) {
-          throw new IllegalStateException(
-              "nothing specified for metric attribute key '" + key + "'");
+  private List<MetricAttribute> addMetricAttributes(Map<String, String> metricAttributeMap) {
+
+    List<MetricAttribute> list = new ArrayList<>();
+    boolean hasStateAttribute = false;
+    for (String key : metricAttributeMap.keySet()) {
+      String target = metricAttributeMap.get(key);
+      if (target == null) {
+        throw new IllegalStateException("nothing specified for metric attribute key '" + key + "'");
+      }
+      MetricAttribute attribute = buildMetricAttribute(key, target.trim());
+      if (attribute.isStateAttribute()) {
+        if (hasStateAttribute) {
+          throw new IllegalArgumentException("only one state attribute is allowed");
         }
-        list.add(buildMetricAttribute(key, target.trim()));
+        hasStateAttribute = true;
       }
+      list.add(attribute);
+    }
+    if (hasStateAttribute && stateMapping.isEmpty()) {
+      throw new IllegalArgumentException("statekey() usage without stateMapping");
     }
+    return list;
   }
 
   private static MetricAttribute buildMetricAttribute(String key, String target) {
     // The recognized forms of target are:
     //  - param(STRING)
     //  - beanattr(STRING)
     //  - const(STRING)
+    //  - statekey()
     // where STRING is the name of the corresponding parameter key, attribute name,
     // or the direct value to use
     int k = target.indexOf(')');
 
     // Check for one of the cases as above
     if (target.startsWith("param(")) {
       if (k > 0) {
+        String jmxAttribute = target.substring(6, k).trim();
         return new MetricAttribute(
-            key, MetricAttributeExtractor.fromObjectNameParameter(target.substring(6, k).trim()));
+            key, MetricAttributeExtractor.fromObjectNameParameter(jmxAttribute));
       }
     } else if (target.startsWith("beanattr(")) {
       if (k > 0) {
-        return new MetricAttribute(
-            key, MetricAttributeExtractor.fromBeanAttribute(target.substring(9, k).trim()));
+        String jmxAttribute = target.substring(9, k).trim();
+        return new MetricAttribute(key, MetricAttributeExtractor.fromBeanAttribute(jmxAttribute));
       }
     } else if (target.startsWith("const(")) {
       if (k > 0) {
-        return new MetricAttribute(
-            key, MetricAttributeExtractor.fromConstant(target.substring(6, k).trim()));
+        String constantValue = target.substring(6, k).trim();
+        return new MetricAttribute(key, MetricAttributeExtractor.fromConstant(constantValue));
       }
+    } else if (target.equals("statekey()")) {
+      return new MetricAttribute(key, null);
     }
 
-    throw new IllegalArgumentException("Invalid metric attribute specification for '" + key + "'");
+    String msg = "Invalid metric attribute specification for '" + key + "': " + target;
+    throw new IllegalArgumentException(msg);
+  }
+
+  public StateMapping getStateMapping() {
+    return stateMapping;
   }
 }