[120] | 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> |
---|