Apache
/
hadoop
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
hadoop-common-project/hadoop-common/CHANGES.txt
View File

@ -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.

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

@ -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);
}

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

@ -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

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

@ -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();

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

@ -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();

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

@ -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

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

@ -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

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

@ -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.
*/

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

@ -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

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

@ -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

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

@ -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;

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

@ -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

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

@ -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);

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

@ -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;
}

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

@ -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;
}

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

@ -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);
}
}