branch-0.23.1/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics/package.html - hadoop - Git at Google

 <html>

 <!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 -->

   <head>
     <title>org.apache.hadoop.metrics</title>
   </head>
 <body>
 This package defines an API for reporting performance metric information.
 <p/>
 The API is abstract so that it can be implemented on top of
 a variety of metrics client libraries.  The choice of
 client library is a configuration option, and different
 modules within the same application can use
 different metrics implementation libraries.
 <p/>
 Sub-packages:
 <dl>
     <dt><code>org.apache.hadoop.metrics.spi</code></dt>
     <dd>The abstract Server Provider Interface package. Those wishing to
     integrate the metrics API with a particular metrics client library should
     extend this package.</dd>

     <dt><code>org.apache.hadoop.metrics.file</code></dt>
     <dd>An implementation package which writes the metric data to
     a file, or sends it to the standard output stream.</dd>

     <dt> <code>org.apache.hadoop.metrics.ganglia</code></dt>
     <dd>An implementation package which sends metric data to
     <a href="http://ganglia.sourceforge.net/">Ganglia</a>.</dd>
 </dl>

 <h3>Introduction to the Metrics API</h3>

 Here is a simple example of how to use this package to report a single
 metric value:
 <pre>
     private ContextFactory contextFactory = ContextFactory.getFactory();

     void reportMyMetric(float myMetric) {
         MetricsContext myContext = contextFactory.getContext("myContext");
         MetricsRecord myRecord = myContext.getRecord("myRecord");
         myRecord.setMetric("myMetric", myMetric);
         myRecord.update();
     }
 </pre>

 In this example there are three names:
 <dl>
   <dt><i>myContext</i></dt>
   <dd>The context name will typically identify either the application, or else a
   module within an application or library.</dd>

   <dt><i>myRecord</i></dt>
   <dd>The record name generally identifies some entity for which a set of
   metrics are to be reported.  For example, you could have a record named
   "cacheStats" for reporting a number of statistics relating to the usage of
   some cache in your application.</dd>

   <dt><i>myMetric</i></dt>
   <dd>This identifies a particular metric.  For example, you might have metrics
   named "cache_hits" and "cache_misses".
   </dd>
 </dl>

 <h3>Tags</h3>

 In some cases it is useful to have multiple records with the same name. For
 example, suppose that you want to report statistics about each disk on a computer.
 In this case, the record name would be something like "diskStats", but you also
 need to identify the disk which is done by adding a <i>tag</i> to the record.
 The code could look something like this:
 <pre>
     private MetricsRecord diskStats =
             contextFactory.getContext("myContext").getRecord("diskStats");

     void reportDiskMetrics(String diskName, float diskBusy, float diskUsed) {
         diskStats.setTag("diskName", diskName);
         diskStats.setMetric("diskBusy", diskBusy);
         diskStats.setMetric("diskUsed", diskUsed);
         diskStats.update();
     }
 </pre>

 <h3>Buffering and Callbacks</h3>

 Data is not sent immediately to the metrics system when
 <code>MetricsRecord.update()</code> is called. Instead it is stored in an
 internal table, and the contents of the table are sent periodically.
 This can be important for two reasons:
 <ol>
     <li>It means that a programmer is free to put calls to this API in an
     inner loop, since updates can be very frequent without slowing down
     the application significantly.</li>
     <li>Some implementations can gain efficiency by combining many metrics
     into a single UDP message.</li>
 </ol>

 The API provides a timer-based callback via the
 <code>registerUpdater()</code> method.  The benefit of this
 versus using <code>java.util.Timer</code> is that the callbacks will be done
 immediately before sending the data, making the data as current as possible.

 <h3>Configuration</h3>

 It is possible to programmatically examine and modify configuration data
 before creating a context, like this:
 <pre>
     ContextFactory factory = ContextFactory.getFactory();
     ... examine and/or modify factory attributes ...
     MetricsContext context = factory.getContext("myContext");
 </pre>
 The factory attributes can be examined and modified using the following
 <code>ContextFactory</code>methods:
 <ul>
     <li><code>Object getAttribute(String attributeName)</code></li>
     <li><code>String[] getAttributeNames()</code></li>
     <li><code>void setAttribute(String name, Object value)</code></li>
     <li><code>void removeAttribute(attributeName)</code></li>
 </ul>

 <p/>
 <code>ContextFactory.getFactory()</code> initializes the factory attributes by
 reading the properties file <code>hadoop-metrics.properties</code> if it exists
 on the class path.

 <p/>
 A factory attribute named:
 <pre>
 <i>contextName</i>.class
 </pre>
 should have as its value the fully qualified name of the class to be
 instantiated by a call of the <code>CodeFactory</code> method
 <code>getContext(<i>contextName</i>)</code>.  If this factory attribute is not
 specified, the default is to instantiate
 <code>org.apache.hadoop.metrics.file.FileContext</code>.

 <p/>
 Other factory attributes are specific to a particular implementation of this
 API and are documented elsewhere.  For example, configuration attributes for
 the file and Ganglia implementations can be found in the javadoc for
 their respective packages.
 </body>
 </html>
	<html>

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<head>
	<title>org.apache.hadoop.metrics</title>
	</head>
	<body>
	This package defines an API for reporting performance metric information.
	<p/>
	The API is abstract so that it can be implemented on top of
	a variety of metrics client libraries. The choice of
	client library is a configuration option, and different
	modules within the same application can use
	different metrics implementation libraries.
	<p/>
	Sub-packages:
	<dl>
	<dt><code>org.apache.hadoop.metrics.spi</code></dt>
	<dd>The abstract Server Provider Interface package. Those wishing to
	integrate the metrics API with a particular metrics client library should
	extend this package.</dd>

	<dt><code>org.apache.hadoop.metrics.file</code></dt>
	<dd>An implementation package which writes the metric data to
	a file, or sends it to the standard output stream.</dd>

	<dt> <code>org.apache.hadoop.metrics.ganglia</code></dt>
	<dd>An implementation package which sends metric data to
	<a href="http://ganglia.sourceforge.net/">Ganglia</a>.</dd>
	</dl>

	<h3>Introduction to the Metrics API</h3>

	Here is a simple example of how to use this package to report a single
	metric value:
	<pre>
	private ContextFactory contextFactory = ContextFactory.getFactory();

	void reportMyMetric(float myMetric) {
	MetricsContext myContext = contextFactory.getContext("myContext");
	MetricsRecord myRecord = myContext.getRecord("myRecord");
	myRecord.setMetric("myMetric", myMetric);
	myRecord.update();
	}
	</pre>

	In this example there are three names:
	<dl>
	<dt><i>myContext</i></dt>
	<dd>The context name will typically identify either the application, or else a
	module within an application or library.</dd>

	<dt><i>myRecord</i></dt>
	<dd>The record name generally identifies some entity for which a set of
	metrics are to be reported. For example, you could have a record named
	"cacheStats" for reporting a number of statistics relating to the usage of
	some cache in your application.</dd>

	<dt><i>myMetric</i></dt>
	<dd>This identifies a particular metric. For example, you might have metrics
	named "cache_hits" and "cache_misses".
	</dd>
	</dl>

	<h3>Tags</h3>

	In some cases it is useful to have multiple records with the same name. For
	example, suppose that you want to report statistics about each disk on a computer.
	In this case, the record name would be something like "diskStats", but you also
	need to identify the disk which is done by adding a <i>tag</i> to the record.
	The code could look something like this:
	<pre>
	private MetricsRecord diskStats =
	contextFactory.getContext("myContext").getRecord("diskStats");

	void reportDiskMetrics(String diskName, float diskBusy, float diskUsed) {
	diskStats.setTag("diskName", diskName);
	diskStats.setMetric("diskBusy", diskBusy);
	diskStats.setMetric("diskUsed", diskUsed);
	diskStats.update();
	}
	</pre>

	<h3>Buffering and Callbacks</h3>

	Data is not sent immediately to the metrics system when
	<code>MetricsRecord.update()</code> is called. Instead it is stored in an
	internal table, and the contents of the table are sent periodically.
	This can be important for two reasons:
	<ol>
	<li>It means that a programmer is free to put calls to this API in an
	inner loop, since updates can be very frequent without slowing down
	the application significantly.</li>
	<li>Some implementations can gain efficiency by combining many metrics
	into a single UDP message.</li>
	</ol>

	The API provides a timer-based callback via the
	<code>registerUpdater()</code> method. The benefit of this
	versus using <code>java.util.Timer</code> is that the callbacks will be done
	immediately before sending the data, making the data as current as possible.

	<h3>Configuration</h3>

	It is possible to programmatically examine and modify configuration data
	before creating a context, like this:
	<pre>
	ContextFactory factory = ContextFactory.getFactory();
	... examine and/or modify factory attributes ...
	MetricsContext context = factory.getContext("myContext");
	</pre>
	The factory attributes can be examined and modified using the following
	<code>ContextFactory</code>methods:
	<ul>
	<li><code>Object getAttribute(String attributeName)</code></li>
	<li><code>String[] getAttributeNames()</code></li>
	<li><code>void setAttribute(String name, Object value)</code></li>
	<li><code>void removeAttribute(attributeName)</code></li>
	</ul>

	<p/>
	<code>ContextFactory.getFactory()</code> initializes the factory attributes by
	reading the properties file <code>hadoop-metrics.properties</code> if it exists
	on the class path.

	<p/>
	A factory attribute named:
	<pre>
	<i>contextName</i>.class
	</pre>
	should have as its value the fully qualified name of the class to be
	instantiated by a call of the <code>CodeFactory</code> method
	<code>getContext(<i>contextName</i>)</code>. If this factory attribute is not
	specified, the default is to instantiate
	<code>org.apache.hadoop.metrics.file.FileContext</code>.

	<p/>
	Other factory attributes are specific to a particular implementation of this
	API and are documented elsewhere. For example, configuration attributes for
	the file and Ganglia implementations can be found in the javadoc for
	their respective packages.
	</body>
	</html>