1 | <html> |
---|
2 | |
---|
3 | <!-- |
---|
4 | Licensed to the Apache Software Foundation (ASF) under one or more |
---|
5 | contributor license agreements. See the NOTICE file distributed with |
---|
6 | this work for additional information regarding copyright ownership. |
---|
7 | The ASF licenses this file to You under the Apache License, Version 2.0 |
---|
8 | (the "License"); you may not use this file except in compliance with |
---|
9 | the License. You may obtain a copy of the License at |
---|
10 | |
---|
11 | http://www.apache.org/licenses/LICENSE-2.0 |
---|
12 | |
---|
13 | Unless required by applicable law or agreed to in writing, software |
---|
14 | distributed under the License is distributed on an "AS IS" BASIS, |
---|
15 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
---|
16 | See the License for the specific language governing permissions and |
---|
17 | limitations under the License. |
---|
18 | --> |
---|
19 | |
---|
20 | <head> |
---|
21 | <title>org.apache.hadoop.metrics</title> |
---|
22 | </head> |
---|
23 | <body> |
---|
24 | This package defines an API for reporting performance metric information. |
---|
25 | <p/> |
---|
26 | The API is abstract so that it can be implemented on top of |
---|
27 | a variety of metrics client libraries. The choice of |
---|
28 | client library is a configuration option, and different |
---|
29 | modules within the same application can use |
---|
30 | different metrics implementation libraries. |
---|
31 | <p/> |
---|
32 | Sub-packages: |
---|
33 | <dl> |
---|
34 | <dt><code>org.apache.hadoop.metrics.spi</code></dt> |
---|
35 | <dd>The abstract Server Provider Interface package. Those wishing to |
---|
36 | integrate the metrics API with a particular metrics client library should |
---|
37 | extend this package.</dd> |
---|
38 | |
---|
39 | <dt><code>org.apache.hadoop.metrics.file</code></dt> |
---|
40 | <dd>An implementation package which writes the metric data to |
---|
41 | a file, or sends it to the standard output stream.</dd> |
---|
42 | |
---|
43 | <dt> <code>org.apache.hadoop.metrics.ganglia</code></dt> |
---|
44 | <dd>An implementation package which sends metric data to |
---|
45 | <a href="http://ganglia.sourceforge.net/">Ganglia</a>.</dd> |
---|
46 | </dl> |
---|
47 | |
---|
48 | <h3>Introduction to the Metrics API</h3> |
---|
49 | |
---|
50 | Here is a simple example of how to use this package to report a single |
---|
51 | metric value: |
---|
52 | <pre> |
---|
53 | private ContextFactory contextFactory = ContextFactory.getFactory(); |
---|
54 | |
---|
55 | void reportMyMetric(float myMetric) { |
---|
56 | MetricsContext myContext = contextFactory.getContext("myContext"); |
---|
57 | MetricsRecord myRecord = myContext.getRecord("myRecord"); |
---|
58 | myRecord.setMetric("myMetric", myMetric); |
---|
59 | myRecord.update(); |
---|
60 | } |
---|
61 | </pre> |
---|
62 | |
---|
63 | In this example there are three names: |
---|
64 | <dl> |
---|
65 | <dt><i>myContext</i></dt> |
---|
66 | <dd>The context name will typically identify either the application, or else a |
---|
67 | module within an application or library.</dd> |
---|
68 | |
---|
69 | <dt><i>myRecord</i></dt> |
---|
70 | <dd>The record name generally identifies some entity for which a set of |
---|
71 | metrics are to be reported. For example, you could have a record named |
---|
72 | "cacheStats" for reporting a number of statistics relating to the usage of |
---|
73 | some cache in your application.</dd> |
---|
74 | |
---|
75 | <dt><i>myMetric</i></dt> |
---|
76 | <dd>This identifies a particular metric. For example, you might have metrics |
---|
77 | named "cache_hits" and "cache_misses". |
---|
78 | </dd> |
---|
79 | </dl> |
---|
80 | |
---|
81 | <h3>Tags</h3> |
---|
82 | |
---|
83 | In some cases it is useful to have multiple records with the same name. For |
---|
84 | example, suppose that you want to report statistics about each disk on a computer. |
---|
85 | In this case, the record name would be something like "diskStats", but you also |
---|
86 | need to identify the disk which is done by adding a <i>tag</i> to the record. |
---|
87 | The code could look something like this: |
---|
88 | <pre> |
---|
89 | private MetricsRecord diskStats = |
---|
90 | contextFactory.getContext("myContext").getRecord("diskStats"); |
---|
91 | |
---|
92 | void reportDiskMetrics(String diskName, float diskBusy, float diskUsed) { |
---|
93 | diskStats.setTag("diskName", diskName); |
---|
94 | diskStats.setMetric("diskBusy", diskBusy); |
---|
95 | diskStats.setMetric("diskUsed", diskUsed); |
---|
96 | diskStats.update(); |
---|
97 | } |
---|
98 | </pre> |
---|
99 | |
---|
100 | <h3>Buffering and Callbacks</h3> |
---|
101 | |
---|
102 | Data is not sent immediately to the metrics system when |
---|
103 | <code>MetricsRecord.update()</code> is called. Instead it is stored in an |
---|
104 | internal table, and the contents of the table are sent periodically. |
---|
105 | This can be important for two reasons: |
---|
106 | <ol> |
---|
107 | <li>It means that a programmer is free to put calls to this API in an |
---|
108 | inner loop, since updates can be very frequent without slowing down |
---|
109 | the application significantly.</li> |
---|
110 | <li>Some implementations can gain efficiency by combining many metrics |
---|
111 | into a single UDP message.</li> |
---|
112 | </ol> |
---|
113 | |
---|
114 | The API provides a timer-based callback via the |
---|
115 | <code>registerUpdater()</code> method. The benefit of this |
---|
116 | versus using <code>java.util.Timer</code> is that the callbacks will be done |
---|
117 | immediately before sending the data, making the data as current as possible. |
---|
118 | |
---|
119 | <h3>Configuration</h3> |
---|
120 | |
---|
121 | It is possible to programmatically examine and modify configuration data |
---|
122 | before creating a context, like this: |
---|
123 | <pre> |
---|
124 | ContextFactory factory = ContextFactory.getFactory(); |
---|
125 | ... examine and/or modify factory attributes ... |
---|
126 | MetricsContext context = factory.getContext("myContext"); |
---|
127 | </pre> |
---|
128 | The factory attributes can be examined and modified using the following |
---|
129 | <code>ContextFactory</code>methods: |
---|
130 | <ul> |
---|
131 | <li><code>Object getAttribute(String attributeName)</code></li> |
---|
132 | <li><code>String[] getAttributeNames()</code></li> |
---|
133 | <li><code>void setAttribute(String name, Object value)</code></li> |
---|
134 | <li><code>void removeAttribute(attributeName)</code></li> |
---|
135 | </ul> |
---|
136 | |
---|
137 | <p/> |
---|
138 | <code>ContextFactory.getFactory()</code> initializes the factory attributes by |
---|
139 | reading the properties file <code>hadoop-metrics.properties</code> if it exists |
---|
140 | on the class path. |
---|
141 | |
---|
142 | <p/> |
---|
143 | A factory attribute named: |
---|
144 | <pre> |
---|
145 | <i>contextName</i>.class |
---|
146 | </pre> |
---|
147 | should have as its value the fully qualified name of the class to be |
---|
148 | instantiated by a call of the <code>CodeFactory</code> method |
---|
149 | <code>getContext(<i>contextName</i>)</code>. If this factory attribute is not |
---|
150 | specified, the default is to instantiate |
---|
151 | <code>org.apache.hadoop.metrics.file.FileContext</code>. |
---|
152 | |
---|
153 | <p/> |
---|
154 | Other factory attributes are specific to a particular implementation of this |
---|
155 | API and are documented elsewhere. For example, configuration attributes for |
---|
156 | the file and Ganglia implementations can be found in the javadoc for |
---|
157 | their respective packages. |
---|
158 | </body> |
---|
159 | </html> |
---|