src/main/asciidoc/_chapters/profiler.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.
  */
 ////

 [[profiler]]
 = Profiler Servlet
 :doctype: book
 :numbered:
 :toc: left
 :icons: font
 :experimental:

 == Background

 HBASE-21926 introduced a new servlet that supports integrated profiling via async-profiler.

 == Prerequisites

 Go to https://github.com/jvm-profiling-tools/async-profiler, download a release appropriate for your platform, and install on every cluster host.
 If 4.6 or later linux, be sure to set proc variables as per 'Basic Usage' section in the
 <a href="https://github.com/jvm-profiling-tools/async-profiler">Async Profiler Home Page</a>
 (Not doing this will draw you diagrams with no content).

 Set `ASYNC_PROFILER_HOME` in the environment (put it in hbase-env.sh) to the root directory of the async-profiler install location, or pass it on the HBase daemon's command line as a system property as `-Dasync.profiler.home=/path/to/async-profiler`.

 == Usage

 Once the prerequisites are satisfied, access to async-profiler is available by way of the HBase UI or direct interaction with the infoserver.

 Examples:

 * To collect 30 second CPU profile of current process (returns FlameGraph svg)
   `curl http://localhost:16030/prof`
 * To collect 1 minute CPU profile of current process and output in tree format (html)
   `curl http://localhost:16030/prof?output=tree&duration=60`
 * To collect 30 second heap allocation profile of current process (returns FlameGraph svg)
   `curl http://localhost:16030/prof?event=alloc`
 * To collect lock contention profile of current process (returns FlameGraph svg)
   `curl http://localhost:16030/prof?event=lock`

 The following event types are supported by async-profiler. Use the 'event' parameter to specify. Default is 'cpu'. Not all operating systems will support all types.

 Perf events:

 * cpu
 * page-faults
 * context-switches
 * cycles
 * instructions
 * cache-references
 * cache-misses
 * branches
 * branch-misses
 * bus-cycles
 * L1-dcache-load-misses
 * LLC-load-misses
 * dTLB-load-misses

 Java events:

 * alloc
 * lock

 The following output formats are supported. Use the 'output' parameter to specify. Default is 'flamegraph'.

 Output formats:

 * summary: A dump of basic profiling statistics.
 * traces: Call traces.
 * flat: Flat profile (top N hot methods).
 * collapsed: Collapsed call traces in the format used by FlameGraph script. This is a collection of call stacks, where each line is a semicolon separated list of frames followed by a counter.
 * svg: FlameGraph in SVG format.
 * tree: Call tree in HTML format.
 * jfr: Call traces in Java Flight Recorder format.

 The 'duration' parameter specifies how long to collect trace data before generating output, specified in seconds. The default is 10 seconds.

 == UI

 In the UI, there is a new entry 'Profiler' in the top menu that will run the default action, which is to profile the CPU usage of the local process for thirty seconds and then produce FlameGraph SVG output.

 == Notes

 The query parameter `pid` can be used to specify the process id of a specific process to be profiled. If this parameter is missing the local process in which the infoserver is embedded will be profiled. Profile targets that are not JVMs might work but is not specifically supported. There are security implications. Access to the infoserver should be appropriately restricted.
	////
	/**
	*
	* 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.
	*/
	////

	[[profiler]]
	= Profiler Servlet
	:doctype: book
	:numbered:
	:toc: left
	:icons: font
	:experimental:

	== Background

	HBASE-21926 introduced a new servlet that supports integrated profiling via async-profiler.

	== Prerequisites

	Go to https://github.com/jvm-profiling-tools/async-profiler, download a release appropriate for your platform, and install on every cluster host.
	If 4.6 or later linux, be sure to set proc variables as per 'Basic Usage' section in the
	<a href="https://github.com/jvm-profiling-tools/async-profiler">Async Profiler Home Page</a>
	(Not doing this will draw you diagrams with no content).

	Set `ASYNC_PROFILER_HOME` in the environment (put it in hbase-env.sh) to the root directory of the async-profiler install location, or pass it on the HBase daemon's command line as a system property as `-Dasync.profiler.home=/path/to/async-profiler`.

	== Usage

	Once the prerequisites are satisfied, access to async-profiler is available by way of the HBase UI or direct interaction with the infoserver.

	Examples:

	* To collect 30 second CPU profile of current process (returns FlameGraph svg)
	`curl http://localhost:16030/prof`
	* To collect 1 minute CPU profile of current process and output in tree format (html)
	`curl http://localhost:16030/prof?output=tree&duration=60`
	* To collect 30 second heap allocation profile of current process (returns FlameGraph svg)
	`curl http://localhost:16030/prof?event=alloc`
	* To collect lock contention profile of current process (returns FlameGraph svg)
	`curl http://localhost:16030/prof?event=lock`

	The following event types are supported by async-profiler. Use the 'event' parameter to specify. Default is 'cpu'. Not all operating systems will support all types.

	Perf events:

	* cpu
	* page-faults
	* context-switches
	* cycles
	* instructions
	* cache-references
	* cache-misses
	* branches
	* branch-misses
	* bus-cycles
	* L1-dcache-load-misses
	* LLC-load-misses
	* dTLB-load-misses

	Java events:

	* alloc
	* lock

	The following output formats are supported. Use the 'output' parameter to specify. Default is 'flamegraph'.

	Output formats:

	* summary: A dump of basic profiling statistics.
	* traces: Call traces.
	* flat: Flat profile (top N hot methods).
	* collapsed: Collapsed call traces in the format used by FlameGraph script. This is a collection of call stacks, where each line is a semicolon separated list of frames followed by a counter.
	* svg: FlameGraph in SVG format.
	* tree: Call tree in HTML format.
	* jfr: Call traces in Java Flight Recorder format.

	The 'duration' parameter specifies how long to collect trace data before generating output, specified in seconds. The default is 10 seconds.

	== UI

	In the UI, there is a new entry 'Profiler' in the top menu that will run the default action, which is to profile the CPU usage of the local process for thirty seconds and then produce FlameGraph SVG output.

	== Notes

	The query parameter `pid` can be used to specify the process id of a specific process to be profiled. If this parameter is missing the local process in which the infoserver is embedded will be profiled. Profile targets that are not JVMs might work but is not specifically supported. There are security implications. Access to the infoserver should be appropriately restricted.