HADOOP-8920. Add more javadoc to metrics2 related classes. Contributed by Suresh Srinivas.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/trunk@1398640 13f79535-47bb-0310-9956-ffa450edef68

hadoop-common-project/hadoop-common/CHANGES.txt

@@ -72,8 +72,8 @@ Trunk (Unreleased)
     HADOOP-8360. empty-configuration.xml fails xml validation
     (Radim Kolar via harsh)
 
-    HADOOP-8367 Improve documentation of declaringClassProtocolName in rpc headers 
-                (Sanjay Radia)
+    HADOOP-8367 Improve documentation of declaringClassProtocolName in 
+    rpc headers. (Sanjay Radia)
 
     HADOOP-8415. Add getDouble() and setDouble() in
     org.apache.hadoop.conf.Configuration (Jan van der Lugt via harsh)
@@ -124,6 +124,8 @@ Trunk (Unreleased)
 
     HADOOP-8910. Add examples to GlobExpander#expand method. (suresh)
 
+    HADOOP-8920. Add more javadoc to metrics2 related classes. (suresh)
+
   BUG FIXES
 
     HADOOP-8177. MBeans shouldn't try to register when it fails to create MBeanName.

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/MetricsCollector.java

@@ -30,14 +30,14 @@ public interface MetricsCollector {
   /**
    * Add a metrics record
    * @param name  of the record
-   * @return  a metrics record builder for the record
+   * @return  a {@link MetricsRecordBuilder} for the record {@code name}
    */
   public MetricsRecordBuilder addRecord(String name);
 
   /**
    * Add a metrics record
    * @param info  of the record
-   * @return  a metrics record builder for the record
+   * @return  a {@link MetricsRecordBuilder} for metrics {@code info}
    */
   public MetricsRecordBuilder addRecord(MetricsInfo info);
 }

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/MetricsFilter.java

@@ -22,7 +22,9 @@ import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.classification.InterfaceStability;
 
 /**
- * The metrics filter interface
+ * The metrics filter interface. The MetricsFilter objects can be used either to
+ * filter the metrics from {@link MetricsSource}s or to filter metrics per
+ * {@link MetricsSink}.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/MetricsInfo.java

@@ -20,19 +20,24 @@ package org.apache.hadoop.metrics2;
 
 import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.classification.InterfaceStability;
+import org.apache.hadoop.metrics2.annotation.Metric;
 
 /**
- * Interface to provide immutable meta info for metrics
+ * Interface to provide immutable metainfo for metrics.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving
 public interface MetricsInfo {
   /**
+   * Typically name corresponds to annotation {@link Metric#value()} or
+   * the name of the class.
    * @return the name of the metric/tag
    */
   String name();
 
   /**
+   * Typically the description corresponds to annotation {@link Metric#about()}
+   * or the name of the class.
    * @return the description of the metric/tag
    */
   String description();

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/MetricsRecord.java

@@ -36,17 +36,17 @@ public interface MetricsRecord {
   long timestamp();
 
   /**
-   * @return the record name
+   * @return the metrics record name
    */
   String name();
 
   /**
-   * @return the description of the record
+   * @return the description of the metrics record
    */
   String description();
 
   /**
-   * @return the context name of the record
+   * @return the context name of the metrics record
    */
   String context();
 

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/MetricsRecordBuilder.java

@@ -28,7 +28,7 @@ import org.apache.hadoop.classification.InterfaceStability;
 @InterfaceStability.Evolving
 public abstract class MetricsRecordBuilder {
   /**
-   * Add a metrics tag
+   * Add a metrics value with metrics information
    * @param info  metadata of the tag
    * @param value of the tag
    * @return self

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/MetricsSink.java

@@ -22,7 +22,11 @@ import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.classification.InterfaceStability;
 
 /**
- * The metrics sink interface
+ * The metrics sink interface. <p>
+ * Implementations of this interface consume the {@link MetricsRecord} generated
+ * from {@link MetricsSource}. It registers with {@link MetricsSystem} which
+ * periodically pushes the {@link MetricsRecord} to the sink using
+ * {@link #putMetrics(MetricsRecord)} method.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/MetricsSource.java

@@ -22,13 +22,15 @@ import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.classification.InterfaceStability;
 
 /**
- * The metrics source interface
+ * The source of metrics information. It generates and updates metrics. It
+ * registers with {@link MetricsSystem}, which periodically polls it to collect
+ * {@link MetricsRecord} and passes it to {@link MetricsSink}.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving
 public interface MetricsSource {
   /**
-   * Get metrics from the source
+   * Get metrics from the metrics source
    * @param collector to contain the resulting metrics snapshot
    * @param all if true, return all metrics even if unchanged.
    */

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/MetricsSystem.java

@@ -22,7 +22,18 @@ import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.classification.InterfaceStability;
 
 /**
- * The metrics system interface
+ * The metrics system interface.
+ * 
+ * The following components are used for metrics.
+ * <ul>
+ * <li>{@link MetricsSource} generate and update metrics information.</li>
+ * <li>{@link MetricsSink} consume the metrics information</li>
+ * </ul>
+ * 
+ * {@link MetricsSource} and {@link MetricsSink} register with the metrics
+ * system. Implementations of {@link MetricsSystem} polls the
+ * {@link MetricsSource}s periodically and pass the {@link MetricsRecord}s to
+ * {@link MetricsSink}.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/annotation/Metric.java

@@ -24,7 +24,8 @@ import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.classification.InterfaceStability;
 
 /**
- * Annotation interface for a single metric
+ * Annotation interface for a single metric used to annotate a field or a method
+ * in the class.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/impl/MetricsRecordBuilderImpl.java

@@ -32,6 +32,14 @@ import org.apache.hadoop.metrics2.MetricsTag;
 import org.apache.hadoop.metrics2.lib.Interns;
 import org.apache.hadoop.util.Time;
 
+/**
+ * {@link MetricsRecordBuilder} implementation used for building metrics records
+ * by the {@link MetricsCollector}. It provides the following functionality:
+ * <ul>
+ * <li>Allows configuring filters for metrics.
+ * </ul>
+ *
+ */
 class MetricsRecordBuilderImpl extends MetricsRecordBuilder {
   private final MetricsCollector parent;
   private final long timestamp;
@@ -41,9 +49,15 @@ class MetricsRecordBuilderImpl extends MetricsRecordBuilder {
   private final MetricsFilter recordFilter, metricFilter;
   private final boolean acceptable;
 
+  /**
+   * @param parent {@link MetricsCollector} using this record builder
+   * @param info metrics information
+   * @param rf
+   * @param mf
+   * @param acceptable
+   */
   MetricsRecordBuilderImpl(MetricsCollector parent, MetricsInfo info,
-                           MetricsFilter rf, MetricsFilter mf,
-                           boolean acceptable) {
+      MetricsFilter rf, MetricsFilter mf, boolean acceptable) {
     this.parent = parent;
     timestamp = Time.now();
     recInfo = info;

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/impl/MetricsRecordImpl.java

@@ -37,7 +37,7 @@ class MetricsRecordImpl extends AbstractMetricsRecord {
 
   /**
    * Construct a metrics record
-   * @param info  {@link MetricInfo} of the record
+   * @param info  {@link MetricsInfo} of the record
    * @param timestamp of the record
    * @param tags  of the record
    * @param metrics of the record

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/impl/MetricsSystemImpl.java

@@ -235,11 +235,9 @@ public class MetricsSystemImpl extends MetricsSystem implements MetricsSource {
   void registerSource(String name, String desc, MetricsSource source) {
     checkNotNull(config, "config");
     MetricsConfig conf = sourceConfigs.get(name);
-    MetricsSourceAdapter sa = conf != null
-        ? new MetricsSourceAdapter(prefix, name, desc, source,
-                                   injectedTags, period, conf)
-        : new MetricsSourceAdapter(prefix, name, desc, source,
-          injectedTags, period, config.subset(SOURCE_KEY));
+    MetricsSourceAdapter sa = new MetricsSourceAdapter(prefix, name, desc,
+        source, injectedTags, period, conf != null ? conf
+            : config.subset(SOURCE_KEY));
     sources.put(name, sa);
     sa.start();
     LOG.debug("Registered source "+ name);

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/lib/DefaultMetricsSystem.java

@@ -27,8 +27,13 @@ import org.apache.hadoop.metrics2.MetricsException;
 import org.apache.hadoop.metrics2.MetricsSystem;
 import org.apache.hadoop.metrics2.impl.MetricsSystemImpl;
 
+import com.google.common.annotations.VisibleForTesting;
+
 /**
- * The default metrics system singleton
+ * The default metrics system singleton. This class is used by all the daemon
+ * processes(such as NameNode, DataNode, JobTracker etc.). During daemon process
+ * initialization the processes call {@link DefaultMetricsSystem#init(String)}
+ * to initialize the {@link MetricsSystem}.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving
@@ -37,7 +42,10 @@ public enum DefaultMetricsSystem {
 
   private AtomicReference<MetricsSystem> impl =
       new AtomicReference<MetricsSystem>(new MetricsSystemImpl());
+  
+  @VisibleForTesting
   volatile boolean miniClusterMode = false;
+  
   final UniqueNames mBeanNames = new UniqueNames();
   final UniqueNames sourceNames = new UniqueNames();
 
@@ -87,12 +95,12 @@ public enum DefaultMetricsSystem {
 
   MetricsSystem getImpl() { return impl.get(); }
 
-  @InterfaceAudience.Private
+  @VisibleForTesting
   public static void setMiniClusterMode(boolean choice) {
     INSTANCE.miniClusterMode = choice;
   }
 
-  @InterfaceAudience.Private
+  @VisibleForTesting
   public static boolean inMiniClusterMode() {
     return INSTANCE.miniClusterMode;
   }

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/lib/MetricsSourceBuilder.java

@@ -35,7 +35,16 @@ import org.apache.hadoop.metrics2.annotation.Metric;
 import org.apache.hadoop.metrics2.annotation.Metrics;
 
 /**
- * Helper class to build metrics source object from annotations
+ * Helper class to build {@link MetricsSource} object from annotations.
+ * <p>
+ * For a given source object:
+ * <ul>
+ * <li>Sets the {@link Field}s annotated with {@link Metric} to
+ * {@link MutableMetric} and adds it to the {@link MetricsRegistry}.</li>
+ * <li>
+ * For {@link Method}s annotated with {@link Metric} creates
+ * {@link MutableMetric} and adds it to the {@link MetricsRegistry}.</li>
+ * </ul>
  */
 @InterfaceAudience.Private
 public class MetricsSourceBuilder {
@@ -115,9 +124,15 @@ public class MetricsSourceBuilder {
     return r;
   }
 
+  /**
+   * Change the declared field {@code field} in {@code source} Object to
+   * {@link MutableMetric}
+   */
   private void add(Object source, Field field) {
     for (Annotation annotation : field.getAnnotations()) {
-      if (!(annotation instanceof Metric)) continue;
+      if (!(annotation instanceof Metric)) {
+        continue;
+      }
       try {
         // skip fields already set
         field.setAccessible(true);
@@ -131,7 +146,7 @@ public class MetricsSourceBuilder {
                                                   registry);
       if (mutable != null) {
         try {
-          field.set(source, mutable);
+          field.set(source, mutable); // Set the source field to MutableMetric
           hasAtMetric = true;
         } catch (Exception e) {
           throw new MetricsException("Error setting field "+ field +
@@ -141,9 +156,12 @@ public class MetricsSourceBuilder {
     }
   }
 
+  /** Add {@link MutableMetric} for a method annotated with {@link Metric} */
   private void add(Object source, Method method) {
     for (Annotation annotation : method.getAnnotations()) {
-      if (!(annotation instanceof Metric)) continue;
+      if (!(annotation instanceof Metric)) {
+        continue;
+      }
       factory.newForMethod(source, method, (Metric) annotation, registry);
       hasAtMetric = true;
     }

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/lib/MutableMetricsFactory.java

@@ -130,6 +130,10 @@ public class MutableMetricsFactory {
     return Interns.info(name2, about.isEmpty() ? name2 : about);
   }
 
+  /**
+   * Remove the prefix "get", if any, from the method name. Return the
+   * capacitalized method name."
+   */
   protected String getName(Method method) {
     String methodName = method.getName();
     if (methodName.startsWith("get")) {
@@ -140,12 +144,15 @@ public class MutableMetricsFactory {
 
   protected MetricsInfo getInfo(Metric annotation, String defaultName) {
     String[] value = annotation.value();
-     if (value.length == 2) {
+    if (value.length == 2) {
+      // Use name and description from the annotation
       return Interns.info(value[0], value[1]);
     }
     if (value.length == 1) {
+      // Use description from the annotation and method name as metric name
       return Interns.info(defaultName, value[0]);
     }
+    // Use method name as metric name and description
     return Interns.info(defaultName, defaultName);
   }
 }