src/main/asciidoc/_chapters/hbtop.adoc - hbase - Git at Google

 ////
 /**
  *
  * 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`
 | -n,--numberOfIterations &lt;arg&gt; | The number of iterations
 | -O,--outputFieldNames | Print each of the available field names on a separate line, then quit
 | -f,--fields &lt;arg&gt; | Show only the given fields. Specify comma separated fields to show multiple fields
 | -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
 | -i,--filters &lt;arg&gt; | The initial filters. Specify comma separated filters to set multiple filters
 | -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
 |=================================

 === Modes

 There are the following 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
 | User | Showing metric records per user
 | Client | Showing metric records per client
 |=================================

 ==== 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
 |=================================

 ==== User mode

 In User mode, the default sort field is `#REQ/S`.

 The fields in this mode are as follows:

 [options="header"]
 |=================================
 | Field | Description | Displayed by default
 | USER | user Name | true
 | #CLIENT | Client Count | true
 | #REQ/S | Request Count per second | true
 | #READ/S | Read Request Count per second | true
 | #WRITE/S | Write Request Count per second | true
 | #FREAD/S | Filtered Read Request Count per second | true
 |=================================

 ==== Client mode

 In Client mode, the default sort field is `#REQ/S`.

 The fields in this mode are as follows:

 [options="header"]
 |=================================
 | Field | Description | Displayed by default
 | CLIENT | Client Hostname | true
 | #USER | User Count | true
 | #REQ/S | Request Count per second | true
 | #READ/S | Read Request Count per second | true
 | #WRITE/S | Write Request Count per second | true
 | #FREAD/S | Filtered Read Request Count per second | 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.
	////
	/**
	*
	* 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 <arg> \| 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 <arg> \| The mode; `n` (Namespace)\| `t` (Table)\| `r` (Region)\| `s` (RegionServer), default is `r`
	\| -n,--numberOfIterations <arg> \| The number of iterations
	\| -O,--outputFieldNames \| Print each of the available field names on a separate line, then quit
	\| -f,--fields <arg> \| Show only the given fields. Specify comma separated fields to show multiple fields
	\| -s,--sortField <arg> \| The initial sort field. You can prepend a `+' or `-' to the field name to also override the sort direction. A leading `+' will force sorting high to low, whereas a `-' will ensure a low to high ordering
	\| -i,--filters <arg> \| The initial filters. Specify comma separated filters to set multiple filters
	\| -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
	\|=================================

	=== Modes

	There are the following 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
	\| User \| Showing metric records per user
	\| Client \| Showing metric records per client
	\|=================================

	==== 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
	\|=================================

	==== User mode

	In User mode, the default sort field is `#REQ/S`.

	The fields in this mode are as follows:

	[options="header"]
	\|=================================
	\| Field \| Description \| Displayed by default
	\| USER \| user Name \| true
	\| #CLIENT \| Client Count \| true
	\| #REQ/S \| Request Count per second \| true
	\| #READ/S \| Read Request Count per second \| true
	\| #WRITE/S \| Write Request Count per second \| true
	\| #FREAD/S \| Filtered Read Request Count per second \| true
	\|=================================

	==== Client mode

	In Client mode, the default sort field is `#REQ/S`.

	The fields in this mode are as follows:

	[options="header"]
	\|=================================
	\| Field \| Description \| Displayed by default
	\| CLIENT \| Client Hostname \| true
	\| #USER \| User Count \| true
	\| #REQ/S \| Request Count per second \| true
	\| #READ/S \| Read Request Count per second \| true
	\| #WRITE/S \| Write Request Count per second \| true
	\| #FREAD/S \| Filtered Read Request Count per second \| 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.