add profiler command scenario #847 (#1421)

site/src/site/sphinx/_include_html/arthas-tutorials.html

@@ -689,6 +689,18 @@
                         cn: "command-tt-cn",
                     }
                 },
+                {
+                    id: "command-profiler",
+                    type: "COMMAND-ENHANCED",
+                    names: {
+                        en: "profiler",
+                        cn: "profiler",
+                    },
+                    ids: {
+                        en: "command-profiler-en",
+                        cn: "command-profiler-cn",
+                    }
+                },
                 {
                     id: "case-web-console",
                     type: "USERCASE",

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

@@ -1,12 +1,25 @@
 profiler
 ===
 
+[`profiler` online tutorial](https://arthas.aliyun.com/doc/arthas-tutorials.html?language=en&id=command-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]`
 
+### Supported Options
+
+|Name|Specification|
+|---:|:---|
+|*action*|Action to execute|
+|*actionArg*|Attribute name pattern|
+|[i:]|sampling interval in ns (default: 10'000'000, i.e. 10 ms)|
+|[f:]|dump output to specified directory|
+|[d:]|run profiling for specified seconds|
+|[e:]|which event to trace (cpu, alloc, lock, cache-misses etc.), default value is cpu|
+
 ### Start profiler
 
 ```

site/src/site/sphinx/profiler.md

@@ -1,12 +1,25 @@
 profiler
 ===
 
+[`profiler`在线教程](https://arthas.aliyun.com/doc/arthas-tutorials.html?language=cn&id=command-profiler)
+
 > 使用[async-profiler](https://github.com/jvm-profiling-tools/async-profiler)生成火焰图
 
 `profiler` 命令支持生成应用热点的火焰图。本质上是通过不断的采样，然后把收集到的采样结果生成火焰图。
 
 `profiler` 命令基本运行结构是 `profiler action [actionArg]`
 
+### 参数说明
+
+|参数名称|参数说明|
+|---:|:---|
+|*action*|要执行的操作|
+|*actionArg*|属性名模式|
+|[i:]|采样间隔（单位：ns）（默认值：10'000'000，即10 ms）|
+|[f:]|将输出转储到指定路径|
+|[d:]|运行评测指定秒|
+|[e:]|要跟踪哪个事件（cpu, alloc, lock, cache-misses等），默认是cpu|
+
 ### 启动profiler
 
 

tutorials/katacoda/command-profiler-cn/arthas-boot.md

@@ -0,0 +1,16 @@
+
+
+
+
+在新的`Terminal 2`里，下载`arthas-boot.jar`，再用`java -jar`命令启动：
+
+`wget https://arthas.aliyun.com/doc/arthas-boot.jar
+java -jar arthas-boot.jar`{{execute T2}}
+
+`arthas-boot`是`Arthas`的启动程序，它启动后，会列出所有的Java进程，用户可以选择需要诊断的目标进程。
+
+选择第一个进程，输入 `1`{{execute T2}} ，再`Enter/回车`：
+
+Attach成功之后，会打印Arthas LOGO。输入 `help`{{execute T2}} 可以获取到更多的帮助信息。
+
+![Arthas Boot](/arthas/scenarios/common-resources/assets/arthas-boot.png)

tutorials/katacoda/command-profiler-cn/arthas-demo.md

@@ -0,0 +1,10 @@
+
+
+
+
+下载`arthas-demo.jar`，再用`java -jar`命令启动：
+
+`wget https://arthas.aliyun.com/doc/arthas-demo.jar
+java -jar arthas-demo.jar`{{execute T1}}
+
+`arthas-demo`是一个很简单的程序，它随机生成整数，再执行因式分解，把结果打印出来。如果生成的随机数是负数，则会打印提示信息。

tutorials/katacoda/command-profiler-cn/finish.md

@@ -0,0 +1,12 @@
+
+在“profiler”中，我们演示了了Arthas的profiler命令。如果有更多的技巧或者使用疑问，欢迎在Issue里提出。
+
+* Issues: https://github.com/alibaba/arthas/issues
+* 文档： https://arthas.aliyun.com/doc
+
+
+如果您在使用Arthas，请让我们知道，您的使用对我们非常重要：[查看](https://github.com/alibaba/arthas/issues/111)
+
+欢迎关注公众号，获取Arthas项目的信息，源码分析，案例实践。
+
+![Arthas公众号](/arthas/scenarios/common-resources/assets/qrcode_gongzhonghao.jpg)

tutorials/katacoda/command-profiler-cn/index.json

@@ -0,0 +1,42 @@
+{
+  "title": "Arthas profiler命令",
+  "description": "Arthas profiler命令",
+  "difficulty": "精通者",
+  "time": "10-20 分钟",
+  "details": {
+    "steps": [
+      {
+        "title": "启动arthas demo",
+        "text": "arthas-demo.md"
+      },
+      {
+        "title": "启动arthas-boot",
+        "text": "arthas-boot.md"
+      },
+      {
+        "title": "profiler命令",
+        "text": "profiler.md"
+      }
+    ],
+    "intro": {
+      "text": "intro.md"
+    },
+    "finish": {
+      "text": "finish.md"
+    }
+  },
+  "environment": {
+    "uilayout": "terminal",
+    "showdashboard": true,
+    "dashboards": [
+      {
+        "name": "Web Port 8563",
+        "port": 8563
+      }
+    ]
+  },
+  "backend": {
+    "imageid": "java",
+    "environmentsprotocol": "http"
+  }
+}

tutorials/katacoda/command-profiler-cn/intro.md

@@ -0,0 +1,23 @@
+
+
+
+![Arthas](https://arthas.aliyun.com/doc/_images/arthas.png)
+
+`Arthas` 是Alibaba开源的Java诊断工具，深受开发者喜爱。在线排查问题，无需重启；动态跟踪Java代码；实时监控JVM状态。
+
+`Arthas` 支持JDK 6+，支持Linux/Mac/Windows，采用命令行交互模式，同时提供丰富的 `Tab` 自动补全功能，进一步方便进行问题的定位和诊断。
+
+当你遇到以下类似问题而束手无策时，Arthas可以帮助你解决：
+
+- 这个类从哪个 jar 包加载的？为什么会报各种类相关的 Exception？
+- 我改的代码为什么没有执行到？难道是我没 commit？分支搞错了？
+- 遇到问题无法在线上 debug，难道只能通过加日志再重新发布吗？
+- 线上遇到某个用户的数据处理有问题，但线上同样无法 debug，线下无法重现！
+- 是否有一个全局视角来查看系统的运行状况？
+- 有什么办法可以监控到JVM的实时运行状态？
+- 怎么快速定位应用的热点，生成火焰图？
+
+本教程会以一个简单的应用为例，演示profiler命令。
+
+* Github: https://github.com/alibaba/arthas
+* 文档: https://arthas.aliyun.com/doc/

tutorials/katacoda/command-profiler-cn/profiler.md

@@ -0,0 +1,208 @@
+
+> 使用[async-profiler](https://github.com/jvm-profiling-tools/async-profiler)生成火焰图
+
+`profiler` 命令支持生成应用热点的火焰图。本质上是通过不断的采样，然后把收集到的采样结果生成火焰图。
+
+`profiler` 命令基本运行结构是 `profiler action [actionArg]`
+
+### 参数说明
+
+|参数名称|参数说明|
+|---:|:---|
+|*action*|要执行的操作|
+|*actionArg*|属性名模式|
+|[i:]|采样间隔（单位：ns）（默认值：10'000'000，即10 ms）|
+|[f:]|将输出转储到指定路径|
+|[d:]|运行评测指定秒|
+|[e:]|要跟踪哪个事件（cpu, alloc, lock, cache-misses等），默认是cpu|
+
+### 查看所有支持的action
+
+`profiler actions`{{execute T2}}
+
+```bash
+$ profiler actions
+Supported Actions: [resume, dumpCollapsed, getSamples, start, list, execute, version, stop, load, dumpFlat, actions, dumpTraces, status]
+```
+
+### 查看版本
+
+`profiler version`{{execute T2}}
+
+```bash
+$ profiler version
+Async-profiler 1.6 built on Sep  9 2019
+Copyright 2019 Andrei Pangin
+```
+
+### 启动profiler
+
+`profiler start -e itimer`{{execute T2}}
+
+```
+$ profiler start -e itimer
+Started [itimer] profiling
+```
+
+> 默认情况下，生成的是cpu的火焰图，即event为`cpu`。可以用`--event`参数来指定。
+> 因为katacoda环境不支持perf_events，所以这里使用`-e itimer`参数指定event为itimer
+
+
+
+### 获取已采集的sample的数量
+
+`profiler getSamples`{{execute T2}}
+
+```
+$ profiler getSamples
+23
+```
+
+### 查看profiler状态
+
+`profiler status`{{execute T2}}
+
+```bash
+$ profiler status
+[itimer] profiling is running for 4 seconds
+```
+
+可以查看当前profiler在采样哪种`event`和采样时间。
+
+### 停止profiler
+
+#### 生成svg格式结果
+
+`profiler stop`{{execute T2}}
+
+```
+$ profiler stop
+profiler output file: /tmp/demo/arthas-output/20191125-135546.svg
+OK
+```
+
+默认情况下，生成的结果保存到应用的`工作目录`下的`arthas-output`目录。可以通过 `--file`参数来指定输出结果路径。比如：
+
+`profiler stop --file /tmp/output.svg`{{execute T2}}
+
+```bash
+$ profiler stop --file /tmp/output.svg
+profiler output file: /tmp/output.svg
+OK
+```
+
+#### 生成html格式结果
+
+默认情况下，结果文件是`svg`格式，如果想生成`html`格式，可以用`--format`参数指定：
+
+`profiler stop --format html`{{execute T2}}
+
+```bash
+$ profiler stop --format html
+profiler output file: /tmp/test/arthas-output/20191125-143329.html
+OK
+```
+
+或者在`--file`参数里用文件名指名格式。比如`--file /tmp/result.html` 。
+
+`profiler stop --file /tmp/result.html`{{execute T2}}
+
+### 通过浏览器查看arthas-output下面的profiler结果
+
+默认情况下，arthas使用8563http端口，则可以打开： https://[[HOST_SUBDOMAIN]]-8563-[[KATACODA_HOST]].environments.katacoda.com/arthas-output/ 目录下面的profiler结果：
+
+![](https://arthas.aliyun.com/doc/_images/arthas-output.jpg)
+
+点击可以查看具体的结果：
+
+![](https://arthas.aliyun.com/doc/_images/arthas-output-svg.jpg)
+
+> 如果是chrome浏览器，可能需要多次刷新。
+
+### profiler支持的events
+
+`profiler list`{{execute T2}}
+
+在不同的平台，不同的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`事件进入采样：
+
+`profiler start --event alloc`{{execute T2}}
+
+```bash
+$ profiler start --event alloc
+```
+
+
+### 恢复采样
+
+`profiler resume`{{execute T2}}
+
+```bash
+$ profiler resume
+Started [cpu] profiling
+```
+
+`start`和`resume`的区别是：`start`是新开始采样，`resume`会保留上次`stop`时的数据。
+
+通过执行`profiler getSamples`可以查看samples的数量来验证。
+
+
+### 使用`execute`来执行复杂的命令
+
+比如开始采样：
+
+`profiler execute 'start'`{{execute T2}}
+
+```bash
+profiler execute 'start'
+```
+
+停止采样，并保存到指定文件里：
+
+`profiler execute 'stop,file=/tmp/result.svg'`{{execute T2}}
+
+```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)

tutorials/katacoda/command-profiler-en/arthas-boot.md

@@ -0,0 +1,16 @@
+
+
+
+
+In the new `Terminal 2`, download `arthas-boot.jar` and start with the `java -jar` command:
+
+`wget https://arthas.aliyun.com/doc/arthas-boot.jar
+java -jar arthas-boot.jar`{{execute T2}}
+
+`arthas-boot` is the launcher for `Arthas`. It lists all the Java processes, and the user can select the target process to be diagnosed.
+
+Select the first process, type `1`{{execute T2}} ，then type `Enter`：
+
+After the Attach is successful, Arthas LOGO is printed. Enter `help`{{execute T2}} for more help.
+
+![Arthas Boot](/arthas/scenarios/common-resources/assets/arthas-boot.png)

tutorials/katacoda/command-profiler-en/arthas-demo.md

@@ -0,0 +1,11 @@
+
+
+
+
+Download `arthas-demo.jar` and start with the `java -jar` command:
+
+`wget https://arthas.aliyun.com/doc/arthas-demo.jar
+java -jar arthas-demo.jar`{{execute T1}}
+
+`arthas-demo` is a very simple program that randomly generates integers, performs factorization, and prints the results.
+If the generated random number is negative, a error message will be printed.

tutorials/katacoda/command-profiler-en/finish.md

@@ -0,0 +1,8 @@
+
+The `profiler Tutorial` demonstrates the usage of profiler. If you have more tips or questions, please feel free to ask in Issue.
+
+* Issues: https://github.com/alibaba/arthas/issues
+* Documentation: https://arthas.aliyun.com/doc/en
+
+
+If you are using Arthas, please let us know. Your use is very important to us: [View](https://github.com/alibaba/arthas/issues/111)

tutorials/katacoda/command-profiler-en/index.json

@@ -0,0 +1,42 @@
+{
+  "title": "Arthas profiler Command",
+  "description": "Arthas profiler Command",
+  "difficulty": "master",
+  "time": "10-20 minutes",
+  "details": {
+    "steps": [
+      {
+        "title": "Arthas demo",
+        "text": "arthas-demo.md"
+      },
+      {
+        "title": "Start arthas-boot",
+        "text": "arthas-boot.md"
+      },
+      {
+        "title": "profiler Command",
+        "text": "profiler.md"
+      }
+    ],
+    "intro": {
+      "text": "intro.md"
+    },
+    "finish": {
+      "text": "finish.md"
+    }
+  },
+  "environment": {
+    "uilayout": "terminal",
+    "showdashboard": true,
+    "dashboards": [
+      {
+        "name": "Web Port 8563",
+        "port": 8563
+      }
+    ]
+  },
+  "backend": {
+    "imageid": "java",
+    "environmentsprotocol": "http"
+  }
+}

tutorials/katacoda/command-profiler-en/intro.md

@@ -0,0 +1,40 @@
+
+
+
+![Arthas](https://arthas.aliyun.com/doc/_images/arthas.png)
+
+`Arthas` is a Java diagnostic tool open-sourced by Alibaba middleware team. Arthas helps developers in trouble-shooting issues in production environment for Java based applications without modifying code or restarting servers.
+
+`Arthas` supports JDK 6+, supports Linux/Mac/Windows.
+
+## Background
+
+Oftentimes the production system network is inaccessible from local development environment. If issues are encountered in production systems, it is impossible to use IDE to debug the application remotely. What’s even worse, debugging in production environment is unacceptable, as it will suspend all the threads, leading to services downtime.
+
+Developers could always try to reproduce the same issue on the test/staging environment. However, this is tricky as some issues cannot be reproduced easily in a different environment, or even disappear once restarted.
+
+And if you’re thinking of adding some logs to your code to help trouble-shoot the issue, you will have to go through the following lifecycle: test, staging, and then to production. Time is money! This approach is inefficient! Worse still, the issue may not be fixed since it might be irreproducible once the JVM is restarted, as described above.
+
+Arthas is built to solve these issues. A developer can troubleshoot production issues on the fly. No JVM restart, no additional code changes. Arthas works as an observer, that is, it will never suspend your running threads.
+
+## Key features
+
+- Check whether a class is loaded? Or where the class is loaded from? (Useful for trouble-shooting jar file conflicts)
+- Decompile a class to ensure the code is running as expected.
+- Check classloader statistics, e.g. the number of classloaders, the number of classes loaded per classloader, the classloader hierarchy, possible classloader leaks, etc.
+- Check the method invocation details, e.g. method parameter, returned values, exceptions and etc.
+- Check the stack trace of specified method invocation. This is useful when a developer wants to know the caller of the method.
+- Trace the method invocation to find slow sub-invocations.
+- Monitor method invocation statistics, e.g. QPS (Query Per Second), RT (Return Time), success rate and etc.
+- Monitor system metrics, thread states and CPU usage, GC statistics and etc.
+- Supports command line interactive mode, with auto-complete feature enabled.
+- Supports telnet and WebSocket, which enables both local and remote diagnostics with command line and browsers.
+- Supports profiler/Flame Graph
+- Supports JDK 6+
+- Supports Linux/Mac/Windows
+
+This tutorial takes a simple application as an example to demonstrate the the usage of profiler.
+
+* Github: https://github.com/alibaba/arthas
+* Docs: https://arthas.aliyun.com/doc/en
+

tutorials/katacoda/command-profiler-en/profiler.md

@@ -0,0 +1,208 @@
+
+> 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]`
+
+### Supported Options
+
+|Name|Specification|
+|---:|:---|
+|*action*|Action to execute|
+|*actionArg*|Attribute name pattern|
+|[i:]|sampling interval in ns (default: 10'000'000, i.e. 10 ms)|
+|[f:]|dump output to specified directory|
+|[d:]|run profiling for specified seconds|
+|[e:]|which event to trace (cpu, alloc, lock, cache-misses etc.), default value is cpu|
+ 
+### View all supported actions
+
+`profiler actions`{{execute T2}}
+
+```bash
+$ profiler actions
+Supported Actions: [resume, dumpCollapsed, getSamples, start, list, execute, version, stop, load, dumpFlat, actions, dumpTraces, status]
+```
+
+
+### View version
+
+`profiler version`{{execute T2}}
+
+```bash
+$ profiler version
+Async-profiler 1.6 built on Sep  9 2019
+Copyright 2019 Andrei Pangin
+```
+
+### Start profiler
+
+`profiler start -e itimer`{{execute T2}}
+
+```
+$ profiler start
+Started [cpu] profiling
+```
+
+> By default, the sample event is `cpu`. Can be specified with the `--event` parameter.
+> Since katacoda environment doesn't support `perf_events`，here use `-e itimer` to specify event to be `itimer`
+
+
+### Get the number of samples collected
+
+`profiler getSamples`{{execute T2}}
+
+```
+$ profiler getSamples
+23
+```
+
+### View profiler status
+
+`profiler status`{{execute T2}}
+
+```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`{{execute T2}}
+
+```
+$ 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:
+
+`profiler stop --file /tmp/output.svg`{{execute T2}}
+
+```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:
+
+`profiler stop --format html`{{execute T2}}
+
+```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`.
+
+`profiler stop --file /tmp/result.html`{{execute T2}}
+
+### View profiler results under arthas-output via browser
+
+By default, arthas uses http port 8563, which can be opened: https://[[HOST_SUBDOMAIN]]-8563-[[KATACODA_HOST]].environments.katacoda.com/arthas-output/ View the `arthas-output` directory below Profiler results:
+
+![](https://arthas.aliyun.com/doc/_images/arthas-output.jpg)
+
+Click to view specific results:
+
+![](https://arthas.aliyun.com/doc/_images/arthas-output-svg.jpg)
+
+> If using the chrome browser, may need to be refreshed multiple times.
+
+### Profiler supported events
+
+`profiler list`{{execute T2}}
+
+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:
+
+`profiler start --event alloc`{{execute T2}}
+
+```bash
+$ profiler start --event alloc
+```
+
+
+### Resume sampling
+
+`profiler resume`{{execute T2}}
+
+```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
+
+`profiler execute 'start'`{{execute T2}}
+
+For example, start sampling:  
+
+```bash
+profiler execute 'start'
+```
+
+Stop sampling and save to the specified file:
+
+`profiler execute 'stop,file=/tmp/result.svg'`{{execute T2}}
+
+```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)