source: proiecte/HadoopJUnit/hadoop-0.20.1/docs/api/org/apache/hadoop/metrics/package-summary.html @ 120

Last change on this file since 120 was 120, checked in by (none), 14 years ago

Added the mail files for the Hadoop JUNit Project
  • Property svn:executable set to *
File size: 13.5 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<!--NewPage-->
3<HTML>
4<HEAD>
5<!-- Generated by javadoc (build 1.6.0_07) on Tue Sep 01 20:57:00 UTC 2009 -->
6<TITLE>
7org.apache.hadoop.metrics (Hadoop 0.20.1 API)
8</TITLE>
9
10<META NAME="date" CONTENT="2009-09-01">
11
12<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../stylesheet.css" TITLE="Style">
13
14<SCRIPT type="text/javascript">
15function windowTitle()
16{
17    if (location.href.indexOf('is-external=true') == -1) {
18        parent.document.title="org.apache.hadoop.metrics (Hadoop 0.20.1 API)";
19    }
20}
21</SCRIPT>
22<NOSCRIPT>
23</NOSCRIPT>
24
25</HEAD>
26
27<BODY BGCOLOR="white" onload="windowTitle();">
28<HR>
29
30
31<!-- ========= START OF TOP NAVBAR ======= -->
32<A NAME="navbar_top"><!-- --></A>
33<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
34<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
35<TR>
36<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
37<A NAME="navbar_top_firstrow"><!-- --></A>
38<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
39  <TR ALIGN="center" VALIGN="top">
40  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
41  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
42  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
43  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
44  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
45  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
46  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
47  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
48  </TR>
49</TABLE>
50</TD>
51<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
52</EM>
53</TD>
54</TR>
55
56<TR>
57<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
58&nbsp;<A HREF="../../../../org/apache/hadoop/mapreduce/lib/reduce/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
59&nbsp;<A HREF="../../../../org/apache/hadoop/metrics/file/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
60<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
61  <A HREF="../../../../index.html?org/apache/hadoop/metrics/package-summary.html" target="_top"><B>FRAMES</B></A>  &nbsp;
62&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
63&nbsp;<SCRIPT type="text/javascript">
64  <!--
65  if(window==top) {
66    document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
67  }
68  //-->
69</SCRIPT>
70<NOSCRIPT>
71  <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
72</NOSCRIPT>
73
74
75</FONT></TD>
76</TR>
77</TABLE>
78<A NAME="skip-navbar_top"></A>
79<!-- ========= END OF TOP NAVBAR ========= -->
80
81<HR>
82<H2>
83Package org.apache.hadoop.metrics
84</H2>
85This package defines an API for reporting performance metric information.
86<P>
87<B>See:</B>
88<BR>
89&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#package_description"><B>Description</B></A>
90<P>
91
92<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
93<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
94<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
95<B>Interface Summary</B></FONT></TH>
96</TR>
97<TR BGCOLOR="white" CLASS="TableRowColor">
98<TD WIDTH="15%"><B><A HREF="../../../../org/apache/hadoop/metrics/MetricsContext.html" title="interface in org.apache.hadoop.metrics">MetricsContext</A></B></TD>
99<TD>The main interface to the metrics package.</TD>
100</TR>
101<TR BGCOLOR="white" CLASS="TableRowColor">
102<TD WIDTH="15%"><B><A HREF="../../../../org/apache/hadoop/metrics/MetricsRecord.html" title="interface in org.apache.hadoop.metrics">MetricsRecord</A></B></TD>
103<TD>A named and optionally tagged set of records to be sent to the metrics
104 system.</TD>
105</TR>
106<TR BGCOLOR="white" CLASS="TableRowColor">
107<TD WIDTH="15%"><B><A HREF="../../../../org/apache/hadoop/metrics/Updater.html" title="interface in org.apache.hadoop.metrics">Updater</A></B></TD>
108<TD>Call-back interface.</TD>
109</TR>
110</TABLE>
111&nbsp;
112
113<P>
114
115<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
116<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
117<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
118<B>Class Summary</B></FONT></TH>
119</TR>
120<TR BGCOLOR="white" CLASS="TableRowColor">
121<TD WIDTH="15%"><B><A HREF="../../../../org/apache/hadoop/metrics/ContextFactory.html" title="class in org.apache.hadoop.metrics">ContextFactory</A></B></TD>
122<TD>Factory class for creating MetricsContext objects.</TD>
123</TR>
124<TR BGCOLOR="white" CLASS="TableRowColor">
125<TD WIDTH="15%"><B><A HREF="../../../../org/apache/hadoop/metrics/MetricsUtil.html" title="class in org.apache.hadoop.metrics">MetricsUtil</A></B></TD>
126<TD>Utility class to simplify creation and reporting of hadoop metrics.</TD>
127</TR>
128</TABLE>
129&nbsp;
130
131<P>
132
133<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
134<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
135<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
136<B>Exception Summary</B></FONT></TH>
137</TR>
138<TR BGCOLOR="white" CLASS="TableRowColor">
139<TD WIDTH="15%"><B><A HREF="../../../../org/apache/hadoop/metrics/MetricsException.html" title="class in org.apache.hadoop.metrics">MetricsException</A></B></TD>
140<TD>General-purpose, unchecked metrics exception.</TD>
141</TR>
142</TABLE>
143&nbsp;
144
145<P>
146<A NAME="package_description"><!-- --></A><H2>
147Package org.apache.hadoop.metrics Description
148</H2>
149
150<P>
151This package defines an API for reporting performance metric information.
152<p/>
153The API is abstract so that it can be implemented on top of
154a variety of metrics client libraries.  The choice of
155client library is a configuration option, and different
156modules within the same application can use
157different metrics implementation libraries.
158<p/>
159Sub-packages:
160<dl>
161    <dt><code>org.apache.hadoop.metrics.spi</code></dt>
162    <dd>The abstract Server Provider Interface package. Those wishing to
163    integrate the metrics API with a particular metrics client library should
164    extend this package.</dd>
165   
166    <dt><code>org.apache.hadoop.metrics.file</code></dt>
167    <dd>An implementation package which writes the metric data to
168    a file, or sends it to the standard output stream.</dd>
169 
170    <dt> <code>org.apache.hadoop.metrics.ganglia</code></dt>
171    <dd>An implementation package which sends metric data to
172    <a href="http://ganglia.sourceforge.net/">Ganglia</a>.</dd>
173</dl>
174
175<h3>Introduction to the Metrics API</h3>
176
177Here is a simple example of how to use this package to report a single
178metric value:
179<pre>
180    private ContextFactory contextFactory = ContextFactory.getFactory();
181   
182    void reportMyMetric(float myMetric) {
183        MetricsContext myContext = contextFactory.getContext("myContext");
184        MetricsRecord myRecord = myContext.getRecord("myRecord");
185        myRecord.setMetric("myMetric", myMetric);
186        myRecord.update();
187    }
188</pre>
189 
190In this example there are three names:
191<dl>
192  <dt><i>myContext</i></dt>
193  <dd>The context name will typically identify either the application, or else a
194  module within an application or library.</dd>
195 
196  <dt><i>myRecord</i></dt>
197  <dd>The record name generally identifies some entity for which a set of
198  metrics are to be reported.  For example, you could have a record named
199  "cacheStats" for reporting a number of statistics relating to the usage of
200  some cache in your application.</dd>
201 
202  <dt><i>myMetric</i></dt>
203  <dd>This identifies a particular metric.  For example, you might have metrics
204  named "cache_hits" and "cache_misses".
205  </dd>
206</dl>
207
208<h3>Tags</h3>
209
210In some cases it is useful to have multiple records with the same name. For
211example, suppose that you want to report statistics about each disk on a computer.
212In this case, the record name would be something like "diskStats", but you also
213need to identify the disk which is done by adding a <i>tag</i> to the record.
214The code could look something like this:
215<pre>
216    private MetricsRecord diskStats =
217            contextFactory.getContext("myContext").getRecord("diskStats");
218           
219    void reportDiskMetrics(String diskName, float diskBusy, float diskUsed) {
220        diskStats.setTag("diskName", diskName);
221        diskStats.setMetric("diskBusy", diskBusy);
222        diskStats.setMetric("diskUsed", diskUsed);
223        diskStats.update();
224    }
225</pre>
226
227<h3>Buffering and Callbacks</h3>
228
229Data is not sent immediately to the metrics system when
230<code>MetricsRecord.update()</code> is called. Instead it is stored in an
231internal table, and the contents of the table are sent periodically.
232This can be important for two reasons:
233<ol>
234    <li>It means that a programmer is free to put calls to this API in an
235    inner loop, since updates can be very frequent without slowing down
236    the application significantly.</li>
237    <li>Some implementations can gain efficiency by combining many metrics
238    into a single UDP message.</li>
239</ol>
240
241The API provides a timer-based callback via the
242<code>registerUpdater()</code> method.  The benefit of this
243versus using <code>java.util.Timer</code> is that the callbacks will be done
244immediately before sending the data, making the data as current as possible.
245
246<h3>Configuration</h3>
247
248It is possible to programmatically examine and modify configuration data
249before creating a context, like this:
250<pre>
251    ContextFactory factory = ContextFactory.getFactory();
252    ... examine and/or modify factory attributes ...
253    MetricsContext context = factory.getContext("myContext");
254</pre>
255The factory attributes can be examined and modified using the following
256<code>ContextFactory</code>methods:
257<ul>
258    <li><code>Object getAttribute(String attributeName)</code></li>
259    <li><code>String[] getAttributeNames()</code></li>
260    <li><code>void setAttribute(String name, Object value)</code></li>
261    <li><code>void removeAttribute(attributeName)</code></li>
262</ul>
263
264<p/>
265<code>ContextFactory.getFactory()</code> initializes the factory attributes by
266reading the properties file <code>hadoop-metrics.properties</code> if it exists
267on the class path.
268
269<p/>
270A factory attribute named:
271<pre>
272<i>contextName</i>.class
273</pre>
274should have as its value the fully qualified name of the class to be
275instantiated by a call of the <code>CodeFactory</code> method
276<code>getContext(<i>contextName</i>)</code>.  If this factory attribute is not
277specified, the default is to instantiate
278<code>org.apache.hadoop.metrics.file.FileContext</code>.
279
280<p/>
281Other factory attributes are specific to a particular implementation of this
282API and are documented elsewhere.  For example, configuration attributes for
283the file and Ganglia implementations can be found in the javadoc for
284their respective packages.
285<P>
286
287<P>
288<DL>
289</DL>
290<HR>
291
292
293<!-- ======= START OF BOTTOM NAVBAR ====== -->
294<A NAME="navbar_bottom"><!-- --></A>
295<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
296<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
297<TR>
298<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
299<A NAME="navbar_bottom_firstrow"><!-- --></A>
300<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
301  <TR ALIGN="center" VALIGN="top">
302  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
303  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
304  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
305  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
306  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
307  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
308  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
309  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
310  </TR>
311</TABLE>
312</TD>
313<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
314</EM>
315</TD>
316</TR>
317
318<TR>
319<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
320&nbsp;<A HREF="../../../../org/apache/hadoop/mapreduce/lib/reduce/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
321&nbsp;<A HREF="../../../../org/apache/hadoop/metrics/file/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
322<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
323  <A HREF="../../../../index.html?org/apache/hadoop/metrics/package-summary.html" target="_top"><B>FRAMES</B></A>  &nbsp;
324&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
325&nbsp;<SCRIPT type="text/javascript">
326  <!--
327  if(window==top) {
328    document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
329  }
330  //-->
331</SCRIPT>
332<NOSCRIPT>
333  <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
334</NOSCRIPT>
335
336
337</FONT></TD>
338</TR>
339</TABLE>
340<A NAME="skip-navbar_bottom"></A>
341<!-- ======== END OF BOTTOM NAVBAR ======= -->
342
343<HR>
344Copyright &copy; 2009 The Apache Software Foundation
345</BODY>
346</HTML>
Note: See TracBrowser for help on using the repository browser.