HBASE-26921 Rewrite the counting cells part in TestMultiVersions (#4316)
[hbase.git] / src / main / asciidoc / _chapters / profiler.adoc
blob9c9911ce7519f54a502847fa372b94070499a450
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 [[profiler]]
23 = Profiler Servlet
24 :doctype: book
25 :numbered:
26 :toc: left
27 :icons: font
28 :experimental:
30 == Background
32 https://issues.apache.org/jira/browse/HBASE-21926[HBASE-21926] introduced a new servlet that
33 supports integrated, on-demand profiling via the
34 https://github.com/jvm-profiling-tools/async-profiler[Async Profiler] project.
36 == Prerequisites
38 Go to the https://github.com/jvm-profiling-tools/async-profiler[Async Profiler Home Page], download
39 a release appropriate for your platform, and install on every cluster host. If running a Linux
40 kernel v4.6 or later, be sure to set proc variables as per the
41 https://github.com/jvm-profiling-tools/async-profiler#basic-usage[Basic Usage] section. Not doing
42 so will result in flame graphs that contain no content.
44 Set `ASYNC_PROFILER_HOME` in the environment (put it in hbase-env.sh) to the root directory of the
45 async-profiler install location, or pass it on the HBase daemon's command line as a system property
46 as `-Dasync.profiler.home=/path/to/async-profiler`.
48 == Usage
50 Once the prerequisites are satisfied, access to async-profiler is available by way of the HBase UI
51 or direct interaction with the infoserver.
53 Examples:
55 * To collect 30 second CPU profile of current process (returns FlameGraph svg)
56   `curl http://localhost:16030/prof`
57 * To collect 1 minute CPU profile of current process and output in tree format (html)
58   `curl http://localhost:16030/prof?output=tree&duration=60`
59 * To collect 30 second heap allocation profile of current process (returns FlameGraph svg)
60   `curl http://localhost:16030/prof?event=alloc`
61 * To collect lock contention profile of current process (returns FlameGraph svg)
62   `curl http://localhost:16030/prof?event=lock`
64 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.
66 Perf events:
68 * cpu
69 * page-faults
70 * context-switches
71 * cycles
72 * instructions
73 * cache-references
74 * cache-misses
75 * branches
76 * branch-misses
77 * bus-cycles
78 * L1-dcache-load-misses
79 * LLC-load-misses
80 * dTLB-load-misses
82 Java events:
84 * alloc
85 * lock
87 The following output formats are supported. Use the 'output' parameter to specify. Default is 'flamegraph'.
89 Output formats:
91 * summary: A dump of basic profiling statistics.
92 * traces: Call traces.
93 * flat: Flat profile (top N hot methods).
94 * 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.
95 * svg: FlameGraph in SVG format.
96 * tree: Call tree in HTML format.
97 * jfr: Call traces in Java Flight Recorder format.
99 The 'duration' parameter specifies how long to collect trace data before generating output, specified in seconds. The default is 10 seconds.
101 == UI
103 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.
105 == Notes
107 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.