blob: c0dc6a6241b3b83ffa0562076069844eeaf36ffe [file] [log] [blame]
<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>
<p><em>Note, this package is deprecated in favor of
<code>org.apache.hadoop.metrics2</code> usage.</em></p>
<p>This package defines an API for reporting performance metric information.</p>
<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>
<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>