HBASE-26921 Rewrite the counting cells part in TestMultiVersions (#4316)
[hbase.git] / src / main / asciidoc / _chapters / hbtop.adoc
blobb8523df398c1ce377d35f6884cc955755f24f928
1 ////
2 /**
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 ////
22 [[hbtop]]
23 = hbtop
24 :doctype: book
25 :numbered:
26 :toc: left
27 :icons: font
28 :experimental:
30 == Overview
32 `hbtop` is a real-time monitoring tool for HBase like Unix's top command.
33 It can display summary information as well as metrics per Region/Namespace/Table/RegionServer.
34 In this tool, you can see the metrics sorted by a selected field and filter the metrics to see only metrics you really want to see.
35 Also, with the drill-down feature, you can find hot regions easily in a top-down manner.
37 == Usage
39 You can run hbtop with the following command:
41 ----
42 $ hbase hbtop
43 ----
45 In this case, the values of `hbase.client.zookeeper.quorum` and `zookeeper.znode.parent` in `hbase-site.xml` in the classpath or the default values of them are used to connect.
47 Or, you can specify your own zookeeper quorum and znode parent as follows:
49 ----
50 $ hbase hbtop -Dhbase.client.zookeeper.quorum=<zookeeper quorum> -Dzookeeper.znode.parent=<znode parent>
51 ----
53 image::https://hbase.apache.org/hbtop-images/top_screen.gif[Top screen]
55 The top screen consists of a summary part and of a metrics part.
56 In the summary part, you can see `HBase Version`, `Cluster ID`, `The number of region servers`, `Region count`, `Average Cluster Load` and `Aggregated Request/s`.
57 In the metrics part, you can see metrics per Region/Namespace/Table/RegionServer depending on the selected mode.
58 The top screen is refreshed in a certain period – 3 seconds by default.
60 === Scrolling metric records
62 You can scroll the metric records in the metrics part.
64 image::https://hbase.apache.org/hbtop-images/scrolling_metric_records.gif[Scrolling metric records]
66 === Command line arguments
68 [options="header"]
69 |=================================
70 | Argument | Description
71 | -d,--delay &lt;arg&gt; | The refresh delay (in seconds); default is 3 seconds
72 | -h,--help | Print usage; for help while the tool is running press `h` key
73 | -m,--mode &lt;arg&gt; | The mode; `n` (Namespace)&#124; `t` (Table)&#124; `r` (Region)&#124; `s` (RegionServer), default is `r`
74 | -n,--numberOfIterations &lt;arg&gt; | The number of iterations
75 | -O,--outputFieldNames | Print each of the available field names on a separate line, then quit
76 | -f,--fields &lt;arg&gt; | Show only the given fields. Specify comma separated fields to show multiple fields
77 | -s,--sortField &lt;arg&gt; | The initial sort field. You can prepend a `&plus;' or `-' to the field name to also override the sort direction. A leading `&plus;' will force sorting high to low, whereas a `-' will ensure a low to high ordering
78 | -i,--filters &lt;arg&gt; | The initial filters. Specify comma separated filters to set multiple filters
79 | -b,--batchMode | Starts hbtop in Batch mode, which could be useful for sending output from hbtop to other programs or to a file. In this mode, hbtop will not accept input and runs until the iterations limit you've set with the `-n' command-line option or until killed
80 |=================================
82 === Modes
84 There are the following modes in hbtop:
86 [options="header"]
87 |=================================
88 | Mode | Description
89 | Region | Showing metric records per region
90 | Namespace | Showing metric records per namespace
91 | Table | Showing metric records per table
92 | RegionServer | Showing metric records per region server
93 | User | Showing metric records per user
94 | Client | Showing metric records per client
95 |=================================
97 ==== Region mode
99 In Region mode, the default sort field is `#REQ/S`.
101 The fields in this mode are as follows:
103 [options="header"]
104 |=================================
105 | Field | Description | Displayed by default
106 | RNAME | Region Name | false
107 | NAMESPACE | Namespace Name | true
108 | TABLE | Table Name | true
109 | SCODE | Start Code | false
110 | REPID | Replica ID | false
111 | REGION | Encoded Region Name | true
112 | RS | Short Region Server Name | true
113 | LRS | Long Region Server Name | false
114 | #REQ/S | Request Count per second | true
115 | #READ/S | Read Request Count per second | true
116 | #FREAD/S | Filtered Read Request Count per second | true
117 | #WRITE/S | Write Request Count per second | true
118 | SF | StoreFile Size | true
119 | USF | Uncompressed StoreFile Size | false
120 | #SF | Number of StoreFiles | true
121 | MEMSTORE | MemStore Size | true
122 | LOCALITY | Block Locality | true
123 | SKEY | Start Key | false
124 | #COMPingCELL | Compacting Cell Count | false
125 | #COMPedCELL | Compacted Cell Count | false
126 | %COMP | Compaction Progress | false
127 | LASTMCOMP | Last Major Compaction Time | false
128 |=================================
130 ==== Namespace mode
132 In Namespace mode, the default sort field is `#REQ/S`.
134 The fields in this mode are as follows:
136 [options="header"]
137 |=================================
138 | Field | Description | Displayed by default
139 | NAMESPACE | Namespace Name | true
140 | #REGION | Region Count | true
141 | #REQ/S | Request Count per second | true
142 | #READ/S | Read Request Count per second | true
143 | #FREAD/S | Filtered Read Request Count per second | true
144 | #WRITE/S | Write Request Count per second | true
145 | SF | StoreFile Size | true
146 | USF | Uncompressed StoreFile Size | false
147 | #SF | Number of StoreFiles | true
148 | MEMSTORE | MemStore Size | true
149 |=================================
151 ==== Table mode
153 In Table mode, the default sort field is `#REQ/S`.
155 The fields in this mode are as follows:
157 [options="header"]
158 |=================================
159 | Field | Description | Displayed by default
160 | NAMESPACE | Namespace Name | true
161 | TABLE | Table Name | true
162 | #REGION | Region Count | true
163 | #REQ/S | Request Count per second | true
164 | #READ/S | Read Request Count per second | true
165 | #FREAD/S | Filtered Read Request Count per second | true
166 | #WRITE/S | Write Request Count per second | true
167 | SF | StoreFile Size | true
168 | USF | Uncompressed StoreFile Size | false
169 | #SF | Number of StoreFiles | true
170 | MEMSTORE | MemStore Size | true
171 |=================================
173 ==== RegionServer mode
175 In RegionServer mode, the default sort field is `#REQ/S`.
177 The fields in this mode are as follows:
179 [options="header"]
180 |=================================
181 | Field | Description | Displayed by default
182 | RS | Short Region Server Name | true
183 | LRS | Long Region Server Name | false
184 | #REGION | Region Count | true
185 | #REQ/S | Request Count per second | true
186 | #READ/S | Read Request Count per second | true
187 | #FREAD/S | Filtered Read Request Count per second | true
188 | #WRITE/S | Write Request Count per second | true
189 | SF | StoreFile Size | true
190 | USF | Uncompressed StoreFile Size | false
191 | #SF | Number of StoreFiles | true
192 | MEMSTORE | MemStore Size | true
193 | UHEAP | Used Heap Size | true
194 | MHEAP | Max Heap Size | true
195 |=================================
197 ==== User mode
199 In User mode, the default sort field is `#REQ/S`.
201 The fields in this mode are as follows:
203 [options="header"]
204 |=================================
205 | Field | Description | Displayed by default
206 | USER | user Name | true
207 | #CLIENT | Client Count | true
208 | #REQ/S | Request Count per second | true
209 | #READ/S | Read Request Count per second | true
210 | #WRITE/S | Write Request Count per second | true
211 | #FREAD/S | Filtered Read Request Count per second | true
212 |=================================
214 ==== Client mode
216 In Client mode, the default sort field is `#REQ/S`.
218 The fields in this mode are as follows:
220 [options="header"]
221 |=================================
222 | Field | Description | Displayed by default
223 | CLIENT | Client Hostname | true
224 | #USER | User Count | true
225 | #REQ/S | Request Count per second | true
226 | #READ/S | Read Request Count per second | true
227 | #WRITE/S | Write Request Count per second | true
228 | #FREAD/S | Filtered Read Request Count per second | true
229 |=================================
231 === Changing mode
233 You can change mode by pressing `m` key in the top screen.
235 image::https://hbase.apache.org/hbtop-images/changing_mode.gif[Changing mode]
237 === Changing the refresh delay
239 You can change the refresh by pressing `d` key in the top screen.
241 image::https://hbase.apache.org/hbtop-images/changing_refresh_delay.gif[Changing the refresh delay]
243 === Changing the displayed fields
245 You can move to the field screen by pressing `f` key in the top screen. In the fields screen, you can change the displayed fields by choosing a field and pressing `d` key or `space` key.
247 image::https://hbase.apache.org/hbtop-images/changing_displayed_fields.gif[Changing the displayed fields]
249 === Changing the sort field
251 You can move to the fields screen by pressing `f` key in the top screen. In the field screen, you can change the sort field by choosing a field and pressing `s`. Also, you can change the sort order (ascending or descending) by pressing `R` key.
253 image::https://hbase.apache.org/hbtop-images/changing_sort_field.gif[Changing the sort field]
255 === Changing the order of the fields
257 You can move to the fields screen by pressing `f` key in the top screen. In the field screen, you can change the order of the fields.
259 image::https://hbase.apache.org/hbtop-images/changing_order_of_fields.gif[Changing the sort field]
261 === Filters
263 You can filter the metric records with the filter feature. We can add filters by pressing `o` key for ignoring case or `O` key for case sensitive.
265 image::https://hbase.apache.org/hbtop-images/adding_filters.gif[Adding filters]
267 The syntax is as follows:
268 ----
269 <Field><Operator><Value>
270 ----
272 For example, we can add filters like the following:
273 ----
274 NAMESPACE==default
275 REQ/S>1000
276 ----
278 The operators we can specify are as follows:
280 [options="header"]
281 |=================================
282 | Operator | Description
283 | = | Partial match
284 | == | Exact match
285 | > | Greater than
286 | >= | Greater than or equal to
287 | < | Less than
288 | <= | Less than and equal to
289 |=================================
291 You can see the current filters by pressing `^o` key and clear them by pressing `=` key.
293 image::https://hbase.apache.org/hbtop-images/showing_and_clearing_filters.gif[Showing and clearing filters]
295 === Drilling down
297 You can drill down the metric record by choosing a metric record that you want to drill down and pressing `i` key in the top screen. With this feature, you can find hot regions easily in a top-down manner.
299 image::https://hbase.apache.org/hbtop-images/driling_down.gif[Drilling down]
301 === Help screen
303 You can see the help screen by pressing `h` key in the top screen.
305 image::https://hbase.apache.org/hbtop-images/help_screen.gif[Help screen]
307 == Others
309 === How hbtop gets the metrics data
311 hbtop gets the metrics from ClusterMetrics which is returned as the result of a call to Admin#getClusterMetrics() on the current HMaster. To add metrics to hbtop, they will need to be exposed via ClusterMetrics.