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
This commit is contained in:
Suresh Srinivas 2012-10-16 04:29:50 +00:00
parent b7887f31fb
commit 41eec8a32b
16 changed files with 103 additions and 31 deletions

View File

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

View File

@ -30,14 +30,14 @@ public interface MetricsCollector {
/** /**
* Add a metrics record * Add a metrics record
* @param name of the 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); public MetricsRecordBuilder addRecord(String name);
/** /**
* Add a metrics record * Add a metrics record
* @param info of the 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); public MetricsRecordBuilder addRecord(MetricsInfo info);
} }

View File

@ -22,7 +22,9 @@
import org.apache.hadoop.classification.InterfaceStability; 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 @InterfaceAudience.Public
@InterfaceStability.Evolving @InterfaceStability.Evolving

View File

@ -20,19 +20,24 @@
import org.apache.hadoop.classification.InterfaceAudience; import org.apache.hadoop.classification.InterfaceAudience;
import org.apache.hadoop.classification.InterfaceStability; 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 @InterfaceAudience.Public
@InterfaceStability.Evolving @InterfaceStability.Evolving
public interface MetricsInfo { public interface MetricsInfo {
/** /**
* Typically name corresponds to annotation {@link Metric#value()} or
* the name of the class.
* @return the name of the metric/tag * @return the name of the metric/tag
*/ */
String name(); String name();
/** /**
* Typically the description corresponds to annotation {@link Metric#about()}
* or the name of the class.
* @return the description of the metric/tag * @return the description of the metric/tag
*/ */
String description(); String description();

View File

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

View File

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

View File

@ -22,7 +22,11 @@
import org.apache.hadoop.classification.InterfaceStability; 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 @InterfaceAudience.Public
@InterfaceStability.Evolving @InterfaceStability.Evolving

View File

@ -22,13 +22,15 @@
import org.apache.hadoop.classification.InterfaceStability; 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 @InterfaceAudience.Public
@InterfaceStability.Evolving @InterfaceStability.Evolving
public interface MetricsSource { public interface MetricsSource {
/** /**
* Get metrics from the source * Get metrics from the metrics source
* @param collector to contain the resulting metrics snapshot * @param collector to contain the resulting metrics snapshot
* @param all if true, return all metrics even if unchanged. * @param all if true, return all metrics even if unchanged.
*/ */

View File

@ -22,7 +22,18 @@
import org.apache.hadoop.classification.InterfaceStability; 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 @InterfaceAudience.Public
@InterfaceStability.Evolving @InterfaceStability.Evolving

View File

@ -24,7 +24,8 @@
import org.apache.hadoop.classification.InterfaceStability; 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 @InterfaceAudience.Public
@InterfaceStability.Evolving @InterfaceStability.Evolving

View File

@ -32,6 +32,14 @@
import org.apache.hadoop.metrics2.lib.Interns; import org.apache.hadoop.metrics2.lib.Interns;
import org.apache.hadoop.util.Time; 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 { class MetricsRecordBuilderImpl extends MetricsRecordBuilder {
private final MetricsCollector parent; private final MetricsCollector parent;
private final long timestamp; private final long timestamp;
@ -41,9 +49,15 @@ class MetricsRecordBuilderImpl extends MetricsRecordBuilder {
private final MetricsFilter recordFilter, metricFilter; private final MetricsFilter recordFilter, metricFilter;
private final boolean acceptable; 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, MetricsRecordBuilderImpl(MetricsCollector parent, MetricsInfo info,
MetricsFilter rf, MetricsFilter mf, MetricsFilter rf, MetricsFilter mf, boolean acceptable) {
boolean acceptable) {
this.parent = parent; this.parent = parent;
timestamp = Time.now(); timestamp = Time.now();
recInfo = info; recInfo = info;

View File

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

View File

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

View File

@ -27,8 +27,13 @@
import org.apache.hadoop.metrics2.MetricsSystem; import org.apache.hadoop.metrics2.MetricsSystem;
import org.apache.hadoop.metrics2.impl.MetricsSystemImpl; 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 @InterfaceAudience.Public
@InterfaceStability.Evolving @InterfaceStability.Evolving
@ -37,7 +42,10 @@ public enum DefaultMetricsSystem {
private AtomicReference<MetricsSystem> impl = private AtomicReference<MetricsSystem> impl =
new AtomicReference<MetricsSystem>(new MetricsSystemImpl()); new AtomicReference<MetricsSystem>(new MetricsSystemImpl());
@VisibleForTesting
volatile boolean miniClusterMode = false; volatile boolean miniClusterMode = false;
final UniqueNames mBeanNames = new UniqueNames(); final UniqueNames mBeanNames = new UniqueNames();
final UniqueNames sourceNames = new UniqueNames(); final UniqueNames sourceNames = new UniqueNames();
@ -87,12 +95,12 @@ MetricsSystem setImpl(MetricsSystem ms) {
MetricsSystem getImpl() { return impl.get(); } MetricsSystem getImpl() { return impl.get(); }
@InterfaceAudience.Private @VisibleForTesting
public static void setMiniClusterMode(boolean choice) { public static void setMiniClusterMode(boolean choice) {
INSTANCE.miniClusterMode = choice; INSTANCE.miniClusterMode = choice;
} }
@InterfaceAudience.Private @VisibleForTesting
public static boolean inMiniClusterMode() { public static boolean inMiniClusterMode() {
return INSTANCE.miniClusterMode; return INSTANCE.miniClusterMode;
} }

View File

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

View File

@ -130,6 +130,10 @@ protected MetricsInfo getInfo(Class<?> cls, Metrics annotation) {
return Interns.info(name2, about.isEmpty() ? name2 : about); 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) { protected String getName(Method method) {
String methodName = method.getName(); String methodName = method.getName();
if (methodName.startsWith("get")) { if (methodName.startsWith("get")) {
@ -140,12 +144,15 @@ protected String getName(Method method) {
protected MetricsInfo getInfo(Metric annotation, String defaultName) { protected MetricsInfo getInfo(Metric annotation, String defaultName) {
String[] value = annotation.value(); 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]); return Interns.info(value[0], value[1]);
} }
if (value.length == 1) { if (value.length == 1) {
// Use description from the annotation and method name as metric name
return Interns.info(defaultName, value[0]); return Interns.info(defaultName, value[0]);
} }
// Use method name as metric name and description
return Interns.info(defaultName, defaultName); return Interns.info(defaultName, defaultName);
} }
} }