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 HBASE-21926 introduced a new servlet that supports integrated profiling via async-profiler.
  33
  34 == Prerequisites
  35
  36 Go to https://github.com/jvm-profiling-tools/async-profiler, download a release appropriate for your platform, and install on every cluster host.
  37 If 4.6 or later linux, be sure to set proc variables as per 'Basic Usage' section in the
  38 <a href="https://github.com/jvm-profiling-tools/async-profiler">Async Profiler Home Page</a>
  39 (Not doing this will draw you diagrams with no content).
  40
  41 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`.
  42
  43 == Usage
  44
  45 Once the prerequisites are satisfied, access to async-profiler is available by way of the HBase UI or direct interaction with the infoserver.
  46
  47 Examples:
  48
  49 * To collect 30 second CPU profile of current process (returns FlameGraph svg)
  50   `curl http://localhost:16030/prof`
  51 * To collect 1 minute CPU profile of current process and output in tree format (html)
  52   `curl http://localhost:16030/prof?output=tree&duration=60`
  53 * To collect 30 second heap allocation profile of current process (returns FlameGraph svg)
  54   `curl http://localhost:16030/prof?event=alloc`
  55 * To collect lock contention profile of current process (returns FlameGraph svg)
  56   `curl http://localhost:16030/prof?event=lock`
  57
  58 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.
  59
  60 Perf events:
  61
  62 * cpu
  63 * page-faults
  64 * context-switches
  65 * cycles
  66 * instructions
  67 * cache-references
  68 * cache-misses
  69 * branches
  70 * branch-misses
  71 * bus-cycles
  72 * L1-dcache-load-misses
  73 * LLC-load-misses
  74 * dTLB-load-misses
  75
  76 Java events:
  77
  78 * alloc
  79 * lock
  80
  81 The following output formats are supported. Use the 'output' parameter to specify. Default is 'flamegraph'.
  82
  83 Output formats:
  84
  85 * summary: A dump of basic profiling statistics.
  86 * traces: Call traces.
  87 * flat: Flat profile (top N hot methods).
  88 * 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.
  89 * svg: FlameGraph in SVG format.
  90 * tree: Call tree in HTML format.
  91 * jfr: Call traces in Java Flight Recorder format.
  92
  93 The 'duration' parameter specifies how long to collect trace data before generating output, specified in seconds. The default is 10 seconds.
  94
  95 == UI
  96
  97 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.
  98
  99 == Notes
 100
 101 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.