Apache
/
hbase
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

HBASE-22986 Add documentation for hbtop (#693) 

Signed-off-by: Peter Somogyi <psomogyi@apache.org>
This commit is contained in:
Toshihiro Suzuki 2019-10-08 13:24:22 +09:00 committed by GitHub
parent 10180e232e
commit 8859651f16
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 270 additions and 248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

248
hbase-hbtop/README.md
View File

@ -1,248 +0,0 @@
<!---
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
# hbtop
## Overview
`hbtop` is a real-time monitoring tool for HBase like Unix's top command.
It can display summary information as well as metrics per Region/Namespace/Table/RegionServer.
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.
Also, with the drill-down feature, you can find hot regions easily in a top-down manner.
## Usage
You can run hbtop with the following command:
```
$ hbase hbtop
```
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.
Or, you can specify your own zookeeper quorum and znode parent as follows:
```
$ hbase hbtop -Dhbase.client.zookeeper.quorum=<zookeeper quorum> -Dzookeeper.znode.parent=<znode parent>
```
![Top screen](img/top_screen.gif "Top screen")
The top screen consists of a summary part and of a metrics part.
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`.
In the metrics part, you can see metrics per Region/Namespace/Table/RegionServer depending on the selected mode.
The top screen is refreshed in a certain period – 3 seconds by default.
### Scrolling metric records
You can scroll the metric records in the metrics part.
![Scrolling metric records](img/scrolling_metric_records.gif "Scrolling metric records")
### Command line arguments
| Argument | Description |
|---|---|
| -d,--delay &lt;arg&gt; | The refresh delay (in seconds); default is 3 seconds |
| -h,--help | Print usage; for help while the tool is running press `h` key |
| -m,--mode &lt;arg&gt; | The mode; `n` (Namespace)&#124;`t` (Table)&#124;r (Region)&#124;`s` (RegionServer), default is `r` (Region) |
### Modes
There are the following 4 modes in hbtop:
| Mode | Description |
|---|---|
| Region | Showing metric records per region |
| Namespace | Showing metric records per namespace |
| Table | Showing metric records per table |
| RegionServer | Showing metric records per region server |
#### Region mode
In Region mode, the default sort field is `#REQ/S`.
The fields in this mode are as follows:
| Field | Description | Displayed by default |
|---|---|---|
| RNAME | Region Name | false |
| NAMESPACE | Namespace Name | true |
| TABLE | Table Name | true |
| SCODE | Start Code | false |
| REPID | Replica ID | false |
| REGION | Encoded Region Name | true |
| RS | Short Region Server Name | true |
| LRS | Long Region Server Name | false |
| #REQ/S | Request Count per second | true |
| #READ/S | Read Request Count per second | true |
| #FREAD/S | Filtered Read Request Count per second | true |
| #WRITE/S | Write Request Count per second | true |
| SF | StoreFile Size | true |
| USF | Uncompressed StoreFile Size | false |
| #SF | Number of StoreFiles | true |
| MEMSTORE | MemStore Size | true |
| LOCALITY | Block Locality | true |
| SKEY | Start Key | false |
| #COMPingCELL | Compacting Cell Count | false |
| #COMPedCELL | Compacted Cell Count | false |
| %COMP | Compaction Progress | false |
| LASTMCOMP | Last Major Compaction Time | false |
#### Namespace mode
In Namespace mode, the default sort field is `#REQ/S`.
The fields in this mode are as follows:
| Field | Description | Displayed by default |
|---|---|---|
| NAMESPACE | Namespace Name | true |
| #REGION | Region Count | true |
| #REQ/S | Request Count per second | true |
| #READ/S | Read Request Count per second | true |
| #FREAD/S | Filtered Read Request Count per second | true |
| #WRITE/S | Write Request Count per second | true |
| SF | StoreFile Size | true |
| USF | Uncompressed StoreFile Size | false |
| #SF | Number of StoreFiles | true |
| MEMSTORE | MemStore Size | true |
#### Table mode
In Table mode, the default sort field is `#REQ/S`.
The fields in this mode are as follows:
| Field | Description | Displayed by default |
|---|---|---|
| NAMESPACE | Namespace Name | true |
| TABLE | Table Name | true |
| #REGION | Region Count | true |
| #REQ/S | Request Count per second | true |
| #READ/S | Read Request Count per second | true |
| #FREAD/S | Filtered Read Request Count per second | true |
| #WRITE/S | Write Request Count per second | true |
| SF | StoreFile Size | true |
| USF | Uncompressed StoreFile Size | false |
| #SF | Number of StoreFiles | true |
| MEMSTORE | MemStore Size | true |
#### RegionServer mode
In RegionServer mode, the default sort field is `#REQ/S`.
The fields in this mode are as follows:
| Field | Description | Displayed by default |
|---|---|---|
| RS | Short Region Server Name | true |
| LRS | Long Region Server Name | false |
| #REGION | Region Count | true |
| #REQ/S | Request Count per second | true |
| #READ/S | Read Request Count per second | true |
| #FREAD/S | Filtered Read Request Count per second | true |
| #WRITE/S | Write Request Count per second | true |
| SF | StoreFile Size | true |
| USF | Uncompressed StoreFile Size | false |
| #SF | Number of StoreFiles | true |
| MEMSTORE | MemStore Size | true |
| UHEAP | Used Heap Size | true |
| MHEAP | Max Heap Size | true |
### Changing mode
You can change mode by pressing `m` key in the top screen.
![Changing mode](img/changing_mode.gif "Changing mode")
### Changing the refresh delay
You can change the refresh by pressing `d` key in the top screen.
![Changing the refresh delay](img/changing_refresh_delay.gif "Changing the refresh delay")
### Changing the displayed fields
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.
![Changing the displayed fields](img/changing_displayed_fields.gif "Changing the displayed fields")
### Changing the sort field
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.
![Changing the sort field](img/changing_sort_field.gif "Changing the sort field")
### Changing the order of the fields
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.
![Changing the order of the fields](img/changing_order_of_fields.gif "Changing the sort field")
### Filters
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.
![Adding filters](img/adding_filters.gif "Adding filters")
The syntax is as follows:
```
<Field><Operator><Value>
```
For example, we can add filters like the following:
```
NAMESPACE==default
REQ/S>1000
```
The operators we can specify are as follows:
| Operator | Description |
|---|---|
| = | Partial match |
| == | Exact match |
| > | Greater than |
| >= | Greater than or equal to |
| < | Less than |
| <= | Less than and equal to |
You can see the current filters by pressing `^o` key and clear them by pressing `=` key.
![Showing and clearing filters](img/showing_and_clearing_filters.gif "Showing and clearing filters")
### Drilling down
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.
![Drilling down](img/driling_down.gif "Drilling down")
### Help screen
You can see the help screen by pressing `h` key in the top screen.
![Help screen](img/help_screen.gif "Help screen")
## Others
### How hbtop gets the metrics data
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.

BIN
hbase-hbtop/img/adding_filters.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.6 MiB

BIN
hbase-hbtop/img/changing_displayed_fields.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.5 MiB

BIN
hbase-hbtop/img/changing_mode.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.2 MiB

BIN
hbase-hbtop/img/changing_order_of_fields.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.7 MiB

BIN
hbase-hbtop/img/changing_refresh_delay.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.2 MiB

BIN
hbase-hbtop/img/changing_sort_field.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.3 MiB

BIN
hbase-hbtop/img/driling_down.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.8 MiB

BIN
hbase-hbtop/img/help_screen.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 909 KiB

BIN
hbase-hbtop/img/scrolling_metric_records.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.3 MiB

BIN
hbase-hbtop/img/showing_and_clearing_filters.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.3 MiB

BIN
hbase-hbtop/img/top_screen.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.0 MiB

269
src/main/asciidoc/_chapters/hbtop.adoc Normal file
View File

@ -0,0 +1,269 @@
////
/**
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
////
[[hbtop]]
= hbtop
:doctype: book
:numbered:
:toc: left
:icons: font
:experimental:
== Overview
`hbtop` is a real-time monitoring tool for HBase like Unix's top command.
It can display summary information as well as metrics per Region/Namespace/Table/RegionServer.
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.
Also, with the drill-down feature, you can find hot regions easily in a top-down manner.
== Usage
You can run hbtop with the following command:
----
$ hbase hbtop
----
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.
Or, you can specify your own zookeeper quorum and znode parent as follows:
----
$ hbase hbtop -Dhbase.client.zookeeper.quorum=<zookeeper quorum> -Dzookeeper.znode.parent=<znode parent>
----
image::https://hbase.apache.org/hbtop-images/top_screen.gif[Top screen]
The top screen consists of a summary part and of a metrics part.
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`.
In the metrics part, you can see metrics per Region/Namespace/Table/RegionServer depending on the selected mode.
The top screen is refreshed in a certain period – 3 seconds by default.
=== Scrolling metric records
You can scroll the metric records in the metrics part.
image::https://hbase.apache.org/hbtop-images/scrolling_metric_records.gif[Scrolling metric records]
=== Command line arguments
[options="header"]
|=================================
| Argument | Description
| -d,--delay &lt;arg&gt; | The refresh delay (in seconds); default is 3 seconds
| -h,--help | Print usage; for help while the tool is running press `h` key
| -m,--mode &lt;arg&gt; | The mode; `n` (Namespace)&#124;`t` (Table)&#124;r (Region)&#124;`s` (RegionServer), default is `r` (Region)
|=================================
=== Modes
There are the following 4 modes in hbtop:
[options="header"]
|=================================
| Mode | Description
| Region | Showing metric records per region
| Namespace | Showing metric records per namespace
| Table | Showing metric records per table
| RegionServer | Showing metric records per region server
|=================================
==== Region mode
In Region mode, the default sort field is `#REQ/S`.
The fields in this mode are as follows:
[options="header"]
|=================================
| Field | Description | Displayed by default
| RNAME | Region Name | false
| NAMESPACE | Namespace Name | true
| TABLE | Table Name | true
| SCODE | Start Code | false
| REPID | Replica ID | false
| REGION | Encoded Region Name | true
| RS | Short Region Server Name | true
| LRS | Long Region Server Name | false
| #REQ/S | Request Count per second | true
| #READ/S | Read Request Count per second | true
| #FREAD/S | Filtered Read Request Count per second | true
| #WRITE/S | Write Request Count per second | true
| SF | StoreFile Size | true
| USF | Uncompressed StoreFile Size | false
| #SF | Number of StoreFiles | true
| MEMSTORE | MemStore Size | true
| LOCALITY | Block Locality | true
| SKEY | Start Key | false
| #COMPingCELL | Compacting Cell Count | false
| #COMPedCELL | Compacted Cell Count | false
| %COMP | Compaction Progress | false
| LASTMCOMP | Last Major Compaction Time | false
|=================================
==== Namespace mode
In Namespace mode, the default sort field is `#REQ/S`.
The fields in this mode are as follows:
[options="header"]
|=================================
| Field | Description | Displayed by default
| NAMESPACE | Namespace Name | true
| #REGION | Region Count | true
| #REQ/S | Request Count per second | true
| #READ/S | Read Request Count per second | true
| #FREAD/S | Filtered Read Request Count per second | true
| #WRITE/S | Write Request Count per second | true
| SF | StoreFile Size | true
| USF | Uncompressed StoreFile Size | false
| #SF | Number of StoreFiles | true
| MEMSTORE | MemStore Size | true
|=================================
==== Table mode
In Table mode, the default sort field is `#REQ/S`.
The fields in this mode are as follows:
[options="header"]
|=================================
| Field | Description | Displayed by default
| NAMESPACE | Namespace Name | true
| TABLE | Table Name | true
| #REGION | Region Count | true
| #REQ/S | Request Count per second | true
| #READ/S | Read Request Count per second | true
| #FREAD/S | Filtered Read Request Count per second | true
| #WRITE/S | Write Request Count per second | true
| SF | StoreFile Size | true
| USF | Uncompressed StoreFile Size | false
| #SF | Number of StoreFiles | true
| MEMSTORE | MemStore Size | true
|=================================
==== RegionServer mode
In RegionServer mode, the default sort field is `#REQ/S`.
The fields in this mode are as follows:
[options="header"]
|=================================
| Field | Description | Displayed by default
| RS | Short Region Server Name | true
| LRS | Long Region Server Name | false
| #REGION | Region Count | true
| #REQ/S | Request Count per second | true
| #READ/S | Read Request Count per second | true
| #FREAD/S | Filtered Read Request Count per second | true
| #WRITE/S | Write Request Count per second | true
| SF | StoreFile Size | true
| USF | Uncompressed StoreFile Size | false
| #SF | Number of StoreFiles | true
| MEMSTORE | MemStore Size | true
| UHEAP | Used Heap Size | true
| MHEAP | Max Heap Size | true
|=================================
=== Changing mode
You can change mode by pressing `m` key in the top screen.
image::https://hbase.apache.org/hbtop-images/changing_mode.gif[Changing mode]
=== Changing the refresh delay
You can change the refresh by pressing `d` key in the top screen.
image::https://hbase.apache.org/hbtop-images/changing_refresh_delay.gif[Changing the refresh delay]
=== Changing the displayed fields
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.
image::https://hbase.apache.org/hbtop-images/changing_displayed_fields.gif[Changing the displayed fields]
=== Changing the sort field
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.
image::https://hbase.apache.org/hbtop-images/changing_sort_field.gif[Changing the sort field]
=== Changing the order of the fields
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.
image::https://hbase.apache.org/hbtop-images/changing_order_of_fields.gif[Changing the sort field]
=== Filters
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.
image::https://hbase.apache.org/hbtop-images/adding_filters.gif[Adding filters]
The syntax is as follows:
----
<Field><Operator><Value>
----
For example, we can add filters like the following:
----
NAMESPACE==default
REQ/S>1000
----
The operators we can specify are as follows:
[options="header"]
|=================================
| Operator | Description
| = | Partial match
| == | Exact match
| > | Greater than
| >= | Greater than or equal to
| < | Less than
| <= | Less than and equal to
|=================================
You can see the current filters by pressing `^o` key and clear them by pressing `=` key.
image::https://hbase.apache.org/hbtop-images/showing_and_clearing_filters.gif[Showing and clearing filters]
=== Drilling down
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.
image::https://hbase.apache.org/hbtop-images/driling_down.gif[Drilling down]
=== Help screen
You can see the help screen by pressing `h` key in the top screen.
image::https://hbase.apache.org/hbtop-images/help_screen.gif[Help screen]
== Others
=== How hbtop gets the metrics data
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.

1
src/main/asciidoc/book.adoc
View File

@ -86,6 +86,7 @@ include::_chapters/pv2.adoc[]
include::_chapters/amv2.adoc[]
include::_chapters/zookeeper.adoc[]
include::_chapters/community.adoc[]
include::_chapters/hbtop.adoc[]
= Appendix