update profiler doc. #923

site/src/site/sphinx/advanced-use.md

@@ -54,6 +54,11 @@
 * [stack](stack.md)——输出当前方法被调用的调用路径
 * [tt](tt.md)——方法执行数据的时空隧道，记录下指定方法每次调用的入参和返回信息，并能对这些不同的时间下调用进行观测
 
+
+## profiler/火焰图
+
+* [profiler](profiler.md)--使用[async-profiler](https://github.com/jvm-profiling-tools/async-profiler)对应用采样，生成火焰图
+
 ## options
 
 * [options](options.md)——查看或设置Arthas全局开关

site/src/site/sphinx/commands.md

@@ -29,6 +29,8 @@
 * [stack](stack.md)
 * [tt](tt.md)
 
+* [profiler](profiler.md)
+
 * [cat](cat.md)
 * [grep](grep.md)
 * [pwd](pwd.md)

site/src/site/sphinx/en/advanced-use.md

@@ -55,6 +55,10 @@ Advanced Usage
 * [options](options.md) - check/set Arthas global options
 
 
+## profiler/frame graph
+
+* [profiler](profiler.md) - use [async-profiler](https://github.com/jvm-profiling-tools/async-profiler) to generate frame graph
+
 ## pipe
 
 Arthas provides `pipe` to process the result returned from commands further, e.g. `sm java.lang.String * | grep 'index'`. Commands supported in `pipe`:

site/src/site/sphinx/en/commands.md

@@ -29,6 +29,8 @@ All Commands
 * [stack](stack.md)
 * [tt](tt.md)
 
+* [profiler](profiler.md)
+
 * [cat](cat.md)
 * [grep](grep.md)
 * [pwd](pwd.md)

site/src/site/sphinx/en/profiler.md

@@ -0,0 +1,170 @@
+profiler
+===
+
+> Generate a flame graph using [async-profiler](https://github.com/jvm-profiling-tools/async-profiler)
+
+The `profiler` command supports generate flame graph for application hotspots.
+
+The basic usage of the `profiler` command is `profiler action [actionArg]`
+
+### Start profiler
+
+```
+$ profiler start
+Started [cpu] profiling
+```
+
+> By default, the sample event is `cpu`. Can be specified with the `--event` parameter.
+
+
+### Get the number of samples collected
+
+```
+$ profiler getSamples
+23
+```
+
+### View profiler status
+
+```bash
+$ profiler status
+[cpu] profiling is running for 4 seconds
+```
+
+Can view which `event` and sampling time.
+
+### Stop profiler
+
+#### Generate svg format results
+
+```
+$ profiler stop
+profiler output file: /tmp/demo/arthas-output/20191125-135546.svg
+OK
+```
+
+By default, the generated results are saved to the `arthas-output` directory under the application's `working directory`. The output result path can be specified by the `--file` parameter. such as:
+
+```bash
+$ profiler stop --file /tmp/output.svg
+profiler output file: /tmp/output.svg
+OK
+```
+
+#### Generating html format results
+
+By default, the result file is `svg` format. If you want to generate the `html` format, you can specify it with the `--format` parameter:
+
+```bash
+$ profiler stop --format html
+profiler output file: /tmp/test/arthas-output/20191125-143329.html
+OK
+```
+
+Or use the file name name format in the `--file` parameter. For example, `--file /tmp/result.html`.
+
+### View profiler results under arthas-output via browser
+
+By default, arthas uses port 3658, which can be opened: [http://localhost:3658/arthas-output/](http://localhost:3658/arthas-output/) View the `arthas-output` directory below Profiler results:
+
+![](_static/arthas-output.jpg)
+
+Click to view specific results:
+
+![](_static/arthas-output-svg.jpg)
+
+> If using the chrome browser, may need to be refreshed multiple times.
+
+### Profiler supported events
+
+Under different platforms and different OSs, the supported events are different. For example, under macos:
+
+```bash
+$ profiler list
+Basic events:
+  cpu
+  alloc
+  lock
+  wall
+  itimer
+```
+
+Under linux
+
+```bash
+$ profiler list
+Basic events:
+  cpu
+  alloc
+  lock
+  wall
+  itimer
+Perf events:
+  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
+  mem:breakpoint
+  trace:tracepoint
+```
+
+If you encounter the permissions/configuration issues of the OS itself and then missing some events, you can refer to the [async-profiler](https://github.com/jvm-profiling-tools/async-profiler) documentation.
+
+You can use the `--event` parameter to specify the event to sample, such as sampling the `alloc` event:
+
+```bash
+$ profiler start --event alloc
+```
+
+
+### Resume sampling
+
+```bash
+$ profiler resume
+Started [cpu] profiling
+```
+
+The difference between `start` and `resume` is: `start` is the new start sampling, `resume` will retain the data of the last `stop`.
+
+You can verify the number of samples by executing `profiler getSamples`.
+
+
+### Use `execute` action to execute complex commands
+
+For example, start sampling:  
+
+```bash
+profiler execute 'start'
+```
+
+Stop sampling and save to the specified file:
+
+```bash
+profiler execute 'stop,file=/tmp/result.svg'
+```
+
+Specific format reference: [arguments.cpp#L34](https://github.com/jvm-profiling-tools/async-profiler/blob/v1.6/src/arguments.cpp#L34)
+
+### View all supported actions
+
+```bash
+$ profiler actions
+Supported Actions: [resume, dumpCollapsed, getSamples, start, list, execute, version, stop, load, dumpFlat, actions, dumpTraces, status]
+```
+
+
+### View version
+
+```bash
+$ profiler version
+Async-profiler 1.6 built on Sep  9 2019
+Copyright 2019 Andrei Pangin
+```

site/src/site/sphinx/profiler.md

@@ -0,0 +1,172 @@
+profiler
+===
+
+> 使用[async-profiler](https://github.com/jvm-profiling-tools/async-profiler)生成火焰图
+
+`profiler` 命令支持生成应用热点的火焰图。本质上是通过不断的采样，然后把收集到的采样结果生成火焰图。
+
+`profiler` 命令基本运行结构是 `profiler action [actionArg]`
+
+### 启动profiler
+
+
+```
+$ profiler start
+Started [cpu] profiling
+```
+
+> 默认情况下，生成的是cpu的火焰图，即event为`cpu`。可以用`--event`参数来指定。
+
+
+### 获取已采集的sample的数量
+
+```
+$ profiler getSamples
+23
+```
+
+### 查看profiler状态
+
+```bash
+$ profiler status
+[cpu] profiling is running for 4 seconds
+```
+
+可以查看当前profiler在采样哪种`event`和采样时间。
+
+### 停止profiler
+
+#### 生成svg格式结果
+
+```
+$ profiler stop
+profiler output file: /tmp/demo/arthas-output/20191125-135546.svg
+OK
+```
+
+默认情况下，生成的结果保存到应用的`工作目录`下的`arthas-output`目录。可以通过 `--file`参数来指定输出结果路径。比如：
+
+```bash
+$ profiler stop --file /tmp/output.svg
+profiler output file: /tmp/output.svg
+OK
+```
+
+#### 生成html格式结果
+
+默认情况下，结果文件是`svg`格式，如果想生成`html`格式，可以用`--format`参数指定：
+
+```bash
+$ profiler stop --format html
+profiler output file: /tmp/test/arthas-output/20191125-143329.html
+OK
+```
+
+或者在`--file`参数里用文件名指名格式。比如`--file /tmp/result.html` 。
+
+
+### 通过浏览器查看arthas-output下面的profiler结果
+
+默认情况下，arthas使用3658端口，则可以打开： [http://localhost:3658/arthas-output/](http://localhost:3658/arthas-output/) 查看到`arthas-output`目录下面的profiler结果：
+
+![](_static/arthas-output.jpg)
+
+点击可以查看具体的结果：
+
+![](_static/arthas-output-svg.jpg)
+
+> 如果是chrome浏览器，可能需要多次刷新。
+
+### profiler支持的events
+
+在不同的平台，不同的OS下面，支持的events各有不同。比如在macos下面：
+
+```bash
+$ profiler list
+Basic events:
+  cpu
+  alloc
+  lock
+  wall
+  itimer
+```
+
+在linux下面
+
+```bash
+$ profiler list
+Basic events:
+  cpu
+  alloc
+  lock
+  wall
+  itimer
+Perf events:
+  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
+  mem:breakpoint
+  trace:tracepoint
+```
+
+如果遇到OS本身的权限/配置问题，然后缺少部分event，可以参考`async-profiler`本身文档：[async-profiler](https://github.com/jvm-profiling-tools/async-profiler)
+
+可以用`--event`参数指定要采样的事件，比如对`alloc`事件进入采样：
+
+```bash
+$ profiler start --event alloc
+```
+
+
+### 恢复采样
+
+```bash
+$ profiler resume
+Started [cpu] profiling
+```
+
+`start`和`resume`的区别是：`start`是新开始采样，`resume`会保留上次`stop`时的数据。
+
+通过执行`profiler getSamples`可以查看samples的数量来验证。
+
+
+### 使用`execute`来执行复杂的命令
+
+比如开始采样：
+
+```bash
+profiler execute 'start'
+```
+
+停止采样，并保存到指定文件里：
+
+```bash
+profiler execute 'stop,file=/tmp/result.svg'
+```
+
+具体的格式参考： [arguments.cpp#L34](https://github.com/jvm-profiling-tools/async-profiler/blob/v1.6/src/arguments.cpp#L34)
+
+### 查看所有支持的action
+
+```bash
+$ profiler actions
+Supported Actions: [resume, dumpCollapsed, getSamples, start, list, execute, version, stop, load, dumpFlat, actions, dumpTraces, status]
+```
+
+
+### 查看版本
+
+```bash
+$ profiler version
+Async-profiler 1.6 built on Sep  9 2019
+Copyright 2019 Andrei Pangin
+```