Add filter for in/excluding metrics by name prefix

Signed-off-by: Fabian Stäber <[email protected]>

Author: fstab

simpleclient/src/main/java/io/prometheus/client/Collector.java

@@ -4,6 +4,7 @@
 import io.prometheus.client.exemplars.Exemplar;
 
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import java.util.regex.Pattern;
 
@@ -17,10 +18,50 @@
  * @see <a href="http://prometheus.io/docs/instrumenting/exposition_formats/">Exposition formats</a>.
  */
 public abstract class Collector {
+
   /**
-   * Return all of the metrics of this Collector.
+   * Return all metrics of this Collector.
    */
   public abstract List<MetricFamilySamples> collect();
+
+  /**
+   * Like {@link #collect()}, but the result may exclude {@code MetricFamilySamples} where
+   * {@code metricNameFilter.test(name)} is {@code false} for all Sample names.
+   * <p>
+   * The default implementation first collects all {@code MetricFamilySamples} and then discards the ones
+   * where {@code metricNameFilter.test(name)} returns {@code false} for all names in
+   * {@link MetricFamilySamples#getNames()}.
+   * To improve performance, collector implementations should override this method to prevent
+   * {@code MetricFamilySamples} from being collected if they will be discarded anyways.
+   * See {@code ThreadExports} for an example.
+   * <p>
+   * Note that the resulting List may contain "false positives", i.e. {@code MetricFamilySamples} where it turns
+   * out that none of the Sample names returns {@code true} for {@code metricNameFilter.test(name)},
+   * or "partial matches", i.e. {@code MetricFamilySamples} where some Sample names return {@code true} for
+   * {@code metricNameFilter.test(name)} but some Sample names return {@code false}.
+   * This is ok, because before we produce the output format we will call
+   * {@link MetricFamilySamples#filter(Predicate)} to strip all Samples where {@code metricNameFilter.test(name)}
+   * returns {@code false}.
+   *
+   * @param metricNameFilter may be {@code null}, indicating that all metrics should be collected.
+   */
+  public List<MetricFamilySamples> collect(Predicate<String> metricNameFilter) {
+    List<MetricFamilySamples> all = collect();
+    if (metricNameFilter == null) {
+      return all;
+    }
+    List<MetricFamilySamples> remaining = new ArrayList<MetricFamilySamples>(all.size());
+    for (MetricFamilySamples mfs : all) {
+      for (String name : mfs.getNames()) {
+        if (metricNameFilter.test(name)) {
+          remaining.add(mfs);
+          break;
+        }
+      }
+    }
+    return remaining;
+  }
+
   public enum Type {
     UNKNOWN, // This is untyped in Prometheus text format.
     COUNTER,
@@ -40,7 +81,11 @@ static public class MetricFamilySamples {
     public final String unit;
     public final Type type;
     public final String help;
-    public final List<Sample> samples;
+    public final List<Sample> samples; // this list can be modified as samples are added/removed.
+
+    public MetricFamilySamples(String name, Type type, String help, List<Sample> samples) {
+      this(name, "", type, help, samples);
+    }
 
     public MetricFamilySamples(String name, String unit, Type type, String help, List<Sample> samples) {
       if (!unit.isEmpty() && !name.endsWith("_" + unit)) {
@@ -72,10 +117,84 @@ public MetricFamilySamples(String name, String unit, Type type, String help, Lis
       this.samples = mungedSamples;
     }
 
-    public MetricFamilySamples(String name, Type type, String help, List<Sample> samples) {
-      this(name, "", type, help, samples);
+    /**
+     *
+     * @param metricNameFilter may be {@link null} indicating that the result contains the complete list of samples.
+     * @return A new MetricFamilySamples containing only the Samples matching the metricNameFilter,
+     *         or {@code null} if no Sample matches.
+     */
+    public MetricFamilySamples filter(Predicate<String> metricNameFilter) {
+      if (metricNameFilter == null) {
+        return this;
+      }
+      List<Sample> remainingSamples = new ArrayList<Sample>(samples.size());
+      for (Sample sample : samples) {
+        if (metricNameFilter.test(sample.name)) {
+          remainingSamples.add(sample);
+        }
+      }
+      if (remainingSamples.isEmpty()) {
+        return null;
+      }
+      return new MetricFamilySamples(name, unit, type, help, remainingSamples);
     }
 
+    /**
+     * List of names that are reserved for Samples in these MetricsFamilySamples.
+     * <p>
+     * This is used in two places:
+     * <ol>
+     *     <li>To check potential name collisions in {@link CollectorRegistry#register(Collector)}.
+     *     <li>To check if a collector may contain metrics matching the metric name filter
+     *         in {@link Collector#collect(Predicate)}.
+     * </ol>
+     * Note that {@code getNames()} always includes the name without suffix, even though some
+     * metrics types (like Counter) will not have a Sample with that name.
+     * The reason is that the name without suffix is used in the metadata comments ({@code # TYPE}, {@code # UNIT},
+     * {@code # HELP}), and as this name <a href="https://github.com/prometheus/common/issues/319">must be unique</a>
+     * we include the name without suffix here as well.
+     */
+    public String[] getNames() {
+      switch (type) {
+        case COUNTER:
+          return new String[]{
+                  name + "_total",
+                  name + "_created",
+                  name
+          };
+        case SUMMARY:
+          return new String[]{
+                  name + "_count",
+                  name + "_sum",
+                  name + "_created",
+                  name
+          };
+        case HISTOGRAM:
+          return new String[]{
+                  name + "_count",
+                  name + "_sum",
+                  name + "_bucket",
+                  name + "_created",
+                  name
+          };
+        case GAUGE_HISTOGRAM:
+          return new String[]{
+                  name + "_gcount",
+                  name + "_gsum",
+                  name + "_bucket",
+                  name
+          };
+        case INFO:
+          return new String[]{
+                  name + "_info",
+                  name
+          };
+        default:
+          return new String[]{name};
+      }
+    }
+
+
     @Override
     public boolean equals(Object obj) {
       if (!(obj instanceof MetricFamilySamples)) {
@@ -204,7 +323,7 @@ public interface Describable {
      *  Usually custom collectors do not have to implement Describable. If
      *  Describable is not implemented and the CollectorRegistry was created
      *  with auto describe enabled (which is the case for the default registry)
-     *  then {@link collect} will be called at registration time instead of
+     *  then {@link #collect} will be called at registration time instead of
      *  describe. If this could cause problems, either implement a proper
      *  describe, or if that's not practical have describe return an empty
      *  list.

simpleclient/src/main/java/io/prometheus/client/CollectorRegistry.java

@@ -117,38 +117,7 @@ private List<String> collectorNames(Collector m) {
 
     List<String> names = new ArrayList<String>();
     for (Collector.MetricFamilySamples family : mfs) {
-      switch (family.type) {
-        case COUNTER:
-          names.add(family.name + "_total");
-          names.add(family.name + "_created");
-          names.add(family.name);
-          break;
-        case SUMMARY:
-          names.add(family.name + "_count");
-          names.add(family.name + "_sum");
-          names.add(family.name + "_created");
-          names.add(family.name);
-          break;
-        case HISTOGRAM:
-          names.add(family.name + "_count");
-          names.add(family.name + "_sum");
-          names.add(family.name + "_bucket");
-          names.add(family.name + "_created");
-          names.add(family.name);
-          break;
-        case GAUGE_HISTOGRAM:
-          names.add(family.name + "_gcount");
-          names.add(family.name + "_gsum");
-          names.add(family.name + "_bucket");
-          names.add(family.name);
-          break;
-        case INFO:
-          names.add(family.name + "_info");
-          names.add(family.name);
-          break;
-        default:
-          names.add(family.name);
-      }
+      names.addAll(Arrays.asList(family.getNames()));
     }
     return names;
   }
@@ -168,83 +137,73 @@ public Enumeration<Collector.MetricFamilySamples> metricFamilySamples() {
    * histogram, you must include the '_count', '_sum' and '_bucket' names.
    */
   public Enumeration<Collector.MetricFamilySamples> filteredMetricFamilySamples(Set<String> includedNames) {
-    return new MetricFamilySamplesEnumeration(includedNames);
+    return new MetricFamilySamplesEnumeration(new MetricNameFilter.Builder().includeNames(includedNames).build());
+  }
+
+  /**
+   * Enumeration of metrics where {@code metricNameFilter.test(name)} returns {@code true} for any {@code name} in
+   * {@link Collector.MetricFamilySamples#getNames()}.
+   * @param metricNameFilter may be {@code null}, indicating that the enumeration should contain all metrics.
+   */
+  public Enumeration<Collector.MetricFamilySamples> filteredMetricFamilySamples(Predicate<String> metricNameFilter) {
+    return new MetricFamilySamplesEnumeration(metricNameFilter);
   }
 
   class MetricFamilySamplesEnumeration implements Enumeration<Collector.MetricFamilySamples> {
 
     private final Iterator<Collector> collectorIter;
     private Iterator<Collector.MetricFamilySamples> metricFamilySamples;
     private Collector.MetricFamilySamples next;
-    private Set<String> includedNames;
+    private final Predicate<String> metricNameFilter;
 
-    MetricFamilySamplesEnumeration(Set<String> includedNames) {
-      this.includedNames = includedNames;
-      collectorIter = includedCollectorIterator(includedNames);
+    MetricFamilySamplesEnumeration(Predicate<String> metricNameFilter) {
+      this.metricNameFilter = metricNameFilter;
+      this.collectorIter = filteredCollectorIterator();
       findNextElement();
     }
 
-    private Iterator<Collector> includedCollectorIterator(Set<String> includedNames) {
-      if (includedNames.isEmpty()) {
+    private Iterator<Collector> filteredCollectorIterator() {
+      if (metricNameFilter == null) {
         return collectors().iterator();
       } else {
         HashSet<Collector> collectors = new HashSet<Collector>();
         synchronized (namesCollectorsLock) {
           for (Map.Entry<String, Collector> entry : namesToCollectors.entrySet()) {
-            if (includedNames.contains(entry.getKey())) {
+            // Note that namesToCollectors contains keys for all combinations of suffixes (_total, _info, etc.).
+            if (metricNameFilter.test(entry.getKey())) {
               collectors.add(entry.getValue());
             }
           }
         }
-
         return collectors.iterator();
       }
     }
 
     MetricFamilySamplesEnumeration() {
-      this(Collections.<String>emptySet());
+      this(null);
     }
 
     private void findNextElement() {
       next = null;
 
       while (metricFamilySamples != null && metricFamilySamples.hasNext()) {
-        next = filter(metricFamilySamples.next());
+        next = metricFamilySamples.next().filter(metricNameFilter);
         if (next != null) {
           return;
         }
       }
 
-      if (next == null) {
-        while (collectorIter.hasNext()) {
-          metricFamilySamples = collectorIter.next().collect().iterator();
-          while (metricFamilySamples.hasNext()) {
-            next = filter(metricFamilySamples.next());
-            if (next != null) {
-              return;
-            }
+      while (collectorIter.hasNext()) {
+        metricFamilySamples = collectorIter.next().collect(metricNameFilter).iterator();
+        while (metricFamilySamples.hasNext()) {
+          next = metricFamilySamples.next().filter(metricNameFilter);
+          if (next != null) {
+            return;
           }
         }
       }
     }
 
-    private Collector.MetricFamilySamples filter(Collector.MetricFamilySamples next) {
-      if (includedNames.isEmpty()) {
-        return next;
-      } else {
-        Iterator<Collector.MetricFamilySamples.Sample> it = next.samples.iterator();
-        while (it.hasNext()) {
-            if (!includedNames.contains(it.next().name)) {
-                it.remove();
-            }
-        }
-        if (next.samples.size() == 0) {
-          return null;
-        }
-        return next;
-      }
-    }
-
     public Collector.MetricFamilySamples nextElement() {
       Collector.MetricFamilySamples current = next;
       if (current == null) {