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:
parent
b7887f31fb
commit
41eec8a32b
@ -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.
|
||||||
|
@ -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);
|
||||||
}
|
}
|
||||||
|
@ -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
|
||||||
|
@ -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();
|
||||||
|
@ -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();
|
||||||
|
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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.
|
||||||
*/
|
*/
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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;
|
||||||
|
@ -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
|
||||||
|
@ -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);
|
||||||
|
@ -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;
|
||||||
}
|
}
|
||||||
|
@ -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;
|
||||||
}
|
}
|
||||||
|
@ -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);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
Loading…
Reference in New Issue
Block a user