diff --git a/site/src/site/sphinx/_static/arthas-output-svg.jpg b/site/src/site/sphinx/_static/arthas-output-svg.jpg new file mode 100644 index 000000000..a424bcb2f Binary files /dev/null and b/site/src/site/sphinx/_static/arthas-output-svg.jpg differ diff --git a/site/src/site/sphinx/_static/arthas-output.jpg b/site/src/site/sphinx/_static/arthas-output.jpg new file mode 100644 index 000000000..2ea05d5a2 Binary files /dev/null and b/site/src/site/sphinx/_static/arthas-output.jpg differ diff --git a/site/src/site/sphinx/advanced-use.md b/site/src/site/sphinx/advanced-use.md index c69873814..2923d544f 100644 --- a/site/src/site/sphinx/advanced-use.md +++ b/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全局开关 diff --git a/site/src/site/sphinx/commands.md b/site/src/site/sphinx/commands.md index c716689c4..506ae3da3 100644 --- a/site/src/site/sphinx/commands.md +++ b/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) diff --git a/site/src/site/sphinx/en/advanced-use.md b/site/src/site/sphinx/en/advanced-use.md index 59c04bbfd..a0676ec52 100644 --- a/site/src/site/sphinx/en/advanced-use.md +++ b/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`: diff --git a/site/src/site/sphinx/en/commands.md b/site/src/site/sphinx/en/commands.md index 7ad6d23f8..98d017fdc 100644 --- a/site/src/site/sphinx/en/commands.md +++ b/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) diff --git a/site/src/site/sphinx/en/profiler.md b/site/src/site/sphinx/en/profiler.md new file mode 100644 index 000000000..c1db463ca --- /dev/null +++ b/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 +``` diff --git a/site/src/site/sphinx/profiler.md b/site/src/site/sphinx/profiler.md new file mode 100644 index 000000000..7d6368e58 --- /dev/null +++ b/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 +```