src/main/asciidoc/_chapters/profiler.adoc

   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 ////
  21
  22 [[profiler]]
  23 = Profiler Servlet
  24 :doctype: book
  25 :numbered:
  26 :toc: left
  27 :icons: font
  28 :experimental:
  29
  30 == Background
  31
  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.
  35
  36 == Prerequisites
  37
  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.
  43
  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`.
  47
  48 == Usage
  49
  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.
  52
  53 Examples:
  54
  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`
  63
  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.
  65
  66 Perf events:
  67
  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
  81
  82 Java events:
  83
  84 * alloc
  85 * lock
  86
  87 The following output formats are supported. Use the 'output' parameter to specify. Default is 'flamegraph'.
  88
  89 Output formats:
  90
  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.
  98
  99 The 'duration' parameter specifies how long to collect trace data before generating output, specified in seconds. The default is 10 seconds.
 100
 101 == UI
 102
 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.
 104
 105 == Notes
 106
 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.