1 | /* |
---|
2 | * MetricsRecord.java |
---|
3 | * |
---|
4 | * Licensed to the Apache Software Foundation (ASF) under one |
---|
5 | * or more contributor license agreements. See the NOTICE file |
---|
6 | * distributed with this work for additional information |
---|
7 | * regarding copyright ownership. The ASF licenses this file |
---|
8 | * to you under the Apache License, Version 2.0 (the |
---|
9 | * "License"); you may not use this file except in compliance |
---|
10 | * with the License. You may obtain a copy of the License at |
---|
11 | * |
---|
12 | * http://www.apache.org/licenses/LICENSE-2.0 |
---|
13 | * |
---|
14 | * Unless required by applicable law or agreed to in writing, software |
---|
15 | * distributed under the License is distributed on an "AS IS" BASIS, |
---|
16 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
---|
17 | * See the License for the specific language governing permissions and |
---|
18 | * limitations under the License. |
---|
19 | */ |
---|
20 | |
---|
21 | package org.apache.hadoop.metrics; |
---|
22 | |
---|
23 | /** |
---|
24 | * A named and optionally tagged set of records to be sent to the metrics |
---|
25 | * system. <p/> |
---|
26 | * |
---|
27 | * A record name identifies the kind of data to be reported. For example, a |
---|
28 | * program reporting statistics relating to the disks on a computer might use |
---|
29 | * a record name "diskStats".<p/> |
---|
30 | * |
---|
31 | * A record has zero or more <i>tags</i>. A tag has a name and a value. To |
---|
32 | * continue the example, the "diskStats" record might use a tag named |
---|
33 | * "diskName" to identify a particular disk. Sometimes it is useful to have |
---|
34 | * more than one tag, so there might also be a "diskType" with value "ide" or |
---|
35 | * "scsi" or whatever.<p/> |
---|
36 | * |
---|
37 | * A record also has zero or more <i>metrics</i>. These are the named |
---|
38 | * values that are to be reported to the metrics system. In the "diskStats" |
---|
39 | * example, possible metric names would be "diskPercentFull", "diskPercentBusy", |
---|
40 | * "kbReadPerSecond", etc.<p/> |
---|
41 | * |
---|
42 | * The general procedure for using a MetricsRecord is to fill in its tag and |
---|
43 | * metric values, and then call <code>update()</code> to pass the record to the |
---|
44 | * client library. |
---|
45 | * Metric data is not immediately sent to the metrics system |
---|
46 | * each time that <code>update()</code> is called. |
---|
47 | * An internal table is maintained, identified by the record name. This |
---|
48 | * table has columns |
---|
49 | * corresponding to the tag and the metric names, and rows |
---|
50 | * corresponding to each unique set of tag values. An update |
---|
51 | * either modifies an existing row in the table, or adds a new row with a set of |
---|
52 | * tag values that are different from all the other rows. Note that if there |
---|
53 | * are no tags, then there can be at most one row in the table. <p/> |
---|
54 | * |
---|
55 | * Once a row is added to the table, its data will be sent to the metrics system |
---|
56 | * on every timer period, whether or not it has been updated since the previous |
---|
57 | * timer period. If this is inappropriate, for example if metrics were being |
---|
58 | * reported by some transient object in an application, the <code>remove()</code> |
---|
59 | * method can be used to remove the row and thus stop the data from being |
---|
60 | * sent.<p/> |
---|
61 | * |
---|
62 | * Note that the <code>update()</code> method is atomic. This means that it is |
---|
63 | * safe for different threads to be updating the same metric. More precisely, |
---|
64 | * it is OK for different threads to call <code>update()</code> on MetricsRecord instances |
---|
65 | * with the same set of tag names and tag values. Different threads should |
---|
66 | * <b>not</b> use the same MetricsRecord instance at the same time. |
---|
67 | */ |
---|
68 | public interface MetricsRecord { |
---|
69 | |
---|
70 | /** |
---|
71 | * Returns the record name. |
---|
72 | * |
---|
73 | * @return the record name |
---|
74 | */ |
---|
75 | public abstract String getRecordName(); |
---|
76 | |
---|
77 | /** |
---|
78 | * Sets the named tag to the specified value. The tagValue may be null, |
---|
79 | * which is treated the same as an empty String. |
---|
80 | * |
---|
81 | * @param tagName name of the tag |
---|
82 | * @param tagValue new value of the tag |
---|
83 | * @throws MetricsException if the tagName conflicts with the configuration |
---|
84 | */ |
---|
85 | public abstract void setTag(String tagName, String tagValue); |
---|
86 | |
---|
87 | /** |
---|
88 | * Sets the named tag to the specified value. |
---|
89 | * |
---|
90 | * @param tagName name of the tag |
---|
91 | * @param tagValue new value of the tag |
---|
92 | * @throws MetricsException if the tagName conflicts with the configuration |
---|
93 | */ |
---|
94 | public abstract void setTag(String tagName, int tagValue); |
---|
95 | |
---|
96 | /** |
---|
97 | * Sets the named tag to the specified value. |
---|
98 | * |
---|
99 | * @param tagName name of the tag |
---|
100 | * @param tagValue new value of the tag |
---|
101 | * @throws MetricsException if the tagName conflicts with the configuration |
---|
102 | */ |
---|
103 | public abstract void setTag(String tagName, long tagValue); |
---|
104 | |
---|
105 | /** |
---|
106 | * Sets the named tag to the specified value. |
---|
107 | * |
---|
108 | * @param tagName name of the tag |
---|
109 | * @param tagValue new value of the tag |
---|
110 | * @throws MetricsException if the tagName conflicts with the configuration |
---|
111 | */ |
---|
112 | public abstract void setTag(String tagName, short tagValue); |
---|
113 | |
---|
114 | /** |
---|
115 | * Sets the named tag to the specified value. |
---|
116 | * |
---|
117 | * @param tagName name of the tag |
---|
118 | * @param tagValue new value of the tag |
---|
119 | * @throws MetricsException if the tagName conflicts with the configuration |
---|
120 | */ |
---|
121 | public abstract void setTag(String tagName, byte tagValue); |
---|
122 | |
---|
123 | /** |
---|
124 | * Removes any tag of the specified name. |
---|
125 | * |
---|
126 | * @param tagName name of a tag |
---|
127 | */ |
---|
128 | public abstract void removeTag(String tagName); |
---|
129 | |
---|
130 | /** |
---|
131 | * Sets the named metric to the specified value. |
---|
132 | * |
---|
133 | * @param metricName name of the metric |
---|
134 | * @param metricValue new value of the metric |
---|
135 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
136 | * conflicts with the configuration |
---|
137 | */ |
---|
138 | public abstract void setMetric(String metricName, int metricValue); |
---|
139 | |
---|
140 | /** |
---|
141 | * Sets the named metric to the specified value. |
---|
142 | * |
---|
143 | * @param metricName name of the metric |
---|
144 | * @param metricValue new value of the metric |
---|
145 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
146 | * conflicts with the configuration |
---|
147 | */ |
---|
148 | public abstract void setMetric(String metricName, long metricValue); |
---|
149 | |
---|
150 | /** |
---|
151 | * Sets the named metric to the specified value. |
---|
152 | * |
---|
153 | * @param metricName name of the metric |
---|
154 | * @param metricValue new value of the metric |
---|
155 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
156 | * conflicts with the configuration |
---|
157 | */ |
---|
158 | public abstract void setMetric(String metricName, short metricValue); |
---|
159 | |
---|
160 | /** |
---|
161 | * Sets the named metric to the specified value. |
---|
162 | * |
---|
163 | * @param metricName name of the metric |
---|
164 | * @param metricValue new value of the metric |
---|
165 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
166 | * conflicts with the configuration |
---|
167 | */ |
---|
168 | public abstract void setMetric(String metricName, byte metricValue); |
---|
169 | |
---|
170 | /** |
---|
171 | * Sets the named metric to the specified value. |
---|
172 | * |
---|
173 | * @param metricName name of the metric |
---|
174 | * @param metricValue new value of the metric |
---|
175 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
176 | * conflicts with the configuration |
---|
177 | */ |
---|
178 | public abstract void setMetric(String metricName, float metricValue); |
---|
179 | |
---|
180 | /** |
---|
181 | * Increments the named metric by the specified value. |
---|
182 | * |
---|
183 | * @param metricName name of the metric |
---|
184 | * @param metricValue incremental value |
---|
185 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
186 | * conflicts with the configuration |
---|
187 | */ |
---|
188 | public abstract void incrMetric(String metricName, int metricValue); |
---|
189 | |
---|
190 | /** |
---|
191 | * Increments the named metric by the specified value. |
---|
192 | * |
---|
193 | * @param metricName name of the metric |
---|
194 | * @param metricValue incremental value |
---|
195 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
196 | * conflicts with the configuration |
---|
197 | */ |
---|
198 | public abstract void incrMetric(String metricName, long metricValue); |
---|
199 | |
---|
200 | /** |
---|
201 | * Increments the named metric by the specified value. |
---|
202 | * |
---|
203 | * @param metricName name of the metric |
---|
204 | * @param metricValue incremental value |
---|
205 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
206 | * conflicts with the configuration |
---|
207 | */ |
---|
208 | public abstract void incrMetric(String metricName, short metricValue); |
---|
209 | |
---|
210 | /** |
---|
211 | * Increments the named metric by the specified value. |
---|
212 | * |
---|
213 | * @param metricName name of the metric |
---|
214 | * @param metricValue incremental value |
---|
215 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
216 | * conflicts with the configuration |
---|
217 | */ |
---|
218 | public abstract void incrMetric(String metricName, byte metricValue); |
---|
219 | |
---|
220 | /** |
---|
221 | * Increments the named metric by the specified value. |
---|
222 | * |
---|
223 | * @param metricName name of the metric |
---|
224 | * @param metricValue incremental value |
---|
225 | * @throws MetricsException if the metricName or the type of the metricValue |
---|
226 | * conflicts with the configuration |
---|
227 | */ |
---|
228 | public abstract void incrMetric(String metricName, float metricValue); |
---|
229 | |
---|
230 | /** |
---|
231 | * Updates the table of buffered data which is to be sent periodically. |
---|
232 | * If the tag values match an existing row, that row is updated; |
---|
233 | * otherwise, a new row is added. |
---|
234 | */ |
---|
235 | public abstract void update(); |
---|
236 | |
---|
237 | /** |
---|
238 | * Removes, from the buffered data table, all rows having tags |
---|
239 | * that equal the tags that have been set on this record. For example, |
---|
240 | * if there are no tags on this record, all rows for this record name |
---|
241 | * would be removed. Or, if there is a single tag on this record, then |
---|
242 | * just rows containing a tag with the same name and value would be removed. |
---|
243 | */ |
---|
244 | public abstract void remove(); |
---|
245 | |
---|
246 | } |
---|