test/arthas
1
0
Fork 0
mirror of https://gitee.com/arthas/arthas.git synced 2024-12-02 04:08:34 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

update watch/trace docs

Browse Source
This commit is contained in:
hengyunabc 2021-08-31 16:06:57 +08:00
parent abad06f035
commit ce2b488f92
7 changed files with 155 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
core/src/main/java/com/taobao/arthas/core/command/monitor200/WatchCommand.java
View File

@ -20,13 +20,12 @@ import com.taobao.middleware.cli.annotations.Summary;
@Name("watch")
@Summary("Display the input/output parameter, return object, and thrown exception of specified method invocation")
@Description(Constants.EXPRESS_DESCRIPTION + "\nExamples:\n" +
" watch -b org.apache.commons.lang.StringUtils isBlank params\n" +
" watch -f org.apache.commons.lang.StringUtils isBlank returnObj\n" +
" watch org.apache.commons.lang.StringUtils isBlank '{params, target, returnObj}' -x 2\n" +
" watch -bf *StringUtils isBlank params\n" +
" watch *StringUtils isBlank params[0]\n" +
" watch org.apache.commons.lang.StringUtils isBlank\n" +
" watch org.apache.commons.lang.StringUtils isBlank '{params, target, returnObj, throwExp}' -x 2\n" +
" watch *StringUtils isBlank params[0] params[0].length==1\n" +
" watch *StringUtils isBlank params '#cost>100'\n" +
" watch -f *StringUtils isBlank params\n" +
" watch *StringUtils isBlank params[0]\n" +
" watch -E -b org\\.apache\\.commons\\.lang\\.StringUtils isBlank params[0]\n" +
" watch javax.servlet.Filter * --exclude-class-pattern com.demo.TestFilter\n" +
Constants.WIKI + Constants.WIKI_HOME + "watch")
@ -59,7 +58,7 @@ public class WatchCommand extends EnhancerCommand {
@Argument(index = 2, argName = "express", required = false)
@DefaultValue("{params, target, returnObj}")
@Description("the content you want to watch, written by ognl.\n" + Constants.EXPRESS_EXAMPLES)
@Description("The content you want to watch, written by ognl. Default value is '{params, target, returnObj}'\n" + Constants.EXPRESS_EXAMPLES)
public void setExpress(String express) {
this.express = express;
}

13
site/src/site/sphinx/en/trace.md
View File

@ -238,3 +238,16 @@ So where is the rest of the time consumed?
2. Instruction consumption. For example, instructions such as `i++`, `getfield`, etc.
3. Possible JVM pause during code execution, such as GC, entering synchronization blocks, etc.
#### Use the -v parameter to print more information
> The watch/trace/monitor/stack/tt commands all support the `-v` parameter.
When the command is executed, there is no output result. There are two possibilities:
1. The matched function is not executed
2. The result of the conditional expression is false
But the user cannot tell which situation is.
Using the `-v` option, the specific value and execution result of `Condition express` will be printed for easy confirmation.

41
site/src/site/sphinx/en/watch.md
View File

@ -15,7 +15,7 @@ There are four different scenarios for `watch` command, which makes it rather co
|---:|:---|
|*class-pattern*|pattern for the class name|
|*method-pattern*|pattern for the method name|
|*expression*|expression to monitor|
|*expression*|expression to watch, default value `{params, target, returnObj}`|
|*condition-expression*|condition expression to filter|
|[b]|before method being invoked|
|[e]|when method encountering exceptions|
@ -30,7 +30,7 @@ F.Y.I
3. at the *watching* point, Arthas will use the *expression* to evaluate the variables and print them out;
4. `in parameters` and `out parameters` are different since they can be modified within the invoked methods; `params` stands for `in parameters` in `-b`while `out parameters` in other *watching* points;
5. there are no `return values` and `exceptions` when using `-b`.
6. In the result of the watch command, the `location` information will be printed. There are three possible values for `location`: `AtEnter`, `AtExit`, and `AtExceptionExit`. Corresponding to the method entry, the method returns normally, and the method throws an exception.
Advanced:
* [Critical fields in *expression*](advice-class.md)
@ -43,25 +43,44 @@ Advanced:
Start `math-game` in [Quick Start](quick-start.md).
#### Check the `out parameters` and `return value`
#### Check the `out parameters`, `this` and `return value`
> The expression to watch, default value `{params, target, returnObj}`
```bash
$ watch demo.MathGame primeFactors "{params,returnObj}" -x 2
Press Ctrl+C to abort.
Affect(class-cnt:1 , method-cnt:1) cost in 44 ms.
ts=2018-12-03 19:16:51; [cost=1.280502ms] result=@ArrayList[
$ watch demo.MathGame primeFactors -x 2
Press Q or Ctrl+C to abort.
Affect(class count: 1 , method count: 1) cost in 32 ms, listenerId: 5
method=demo.MathGame.primeFactors location=AtExceptionExit
ts=2021-08-31 15:22:57; [cost=0.220625ms] result=@ArrayList[
@Object[][
@Integer[-179173],
],
@MathGame[
random=@Random[java.util.Random@31cefde0],
illegalArgumentCount=@Integer[44],
],
null,
]
method=demo.MathGame.primeFactors location=AtExit
ts=2021-08-31 15:22:58; [cost=1.020982ms] result=@ArrayList[
@Object[][
@Integer[1],
],
@MathGame[
random=@Random[java.util.Random@31cefde0],
illegalArgumentCount=@Integer[44],
],
@ArrayList[
@Integer[3],
@Integer[19],
@Integer[191],
@Integer[49199],
@Integer[2],
@Integer[2],
@Integer[26947],
],
]
```
* In the above result, the method is executed twice, the first result is `location=AtExceptionExit`, indicating that the method throws an exception, so `returnObj` is null
* In the second result is `location=AtExit`, indicating that the method returns normally, so you can see that the result of `returnObj` is an ArrayList
#### Check `in parameters`
```bash

15
site/src/site/sphinx/trace.md
View File

@ -241,4 +241,17 @@ Affect(class count: 1 , method count: 1) cost in 66 ms, listenerId: 1
```
2. 非函数调用的指令消耗。比如 `i++`, `getfield`等指令。
3. 在代码执行过程中，JVM可能出现停顿，比如GC，进入同步块等。
3. 在代码执行过程中，JVM可能出现停顿，比如GC，进入同步块等。
#### 使用 -v 参数打印更多信息
> watch/trace/monitor/stack/tt 命令都支持 `-v` 参数
当命令执行之后，没有输出结果。有两种可能：
1. 匹配到的函数没有被执行
2. 条件表达式结果是 false
但用户区分不出是哪种情况。
使用 `-v`选项，则会打印`Condition express`的具体值和执行结果，方便确认。

43
site/src/site/sphinx/watch.md
View File

@ -15,7 +15,7 @@ watch 的参数比较多，主要是因为它能在 4 个不同的场景观察
|---:|:---|
|*class-pattern*|类名表达式匹配|
|*method-pattern*|方法名表达式匹配|
|*express*|观察表达式|
|*express*|观察表达式，默认值：`{params, target, returnObj}`|
|*condition-express*|条件表达式|
|[b]|在**方法调用之前**观察|
|[e]|在**方法异常之后**观察|
@ -37,32 +37,53 @@ watch 的参数比较多，主要是因为它能在 4 个不同的场景观察
* 4个观察事件点 `-b`、`-e`、`-s` 默认关闭，`-f` 默认打开，当指定观察点被打开后，在相应事件点会对观察表达式进行求值并输出
* 这里要注意`方法入参`和`方法出参`的区别，有可能在中间被修改导致前后不一致，除了 `-b` 事件点 `params` 代表方法入参外，其余事件都代表方法出参
* 当使用 `-b` 时，由于观察事件点是在方法调用前，此时返回值或异常均不存在
* 在watch命令的结果里，会打印出`location`信息。`location`有三种可能值：`AtEnter`，`AtExit`，`AtExceptionExit`。对应函数入口，函数正常return，函数抛出异常。
### 使用参考
#### 启动 Demo
启动[快速入门](quick-start.md)里的`math-game`。
#### 观察方法出参和返回值
#### 观察方法出参、this对象和返回值
> 观察表达式，默认值是`{params, target, returnObj}`
```bash
$ watch demo.MathGame primeFactors "{params,returnObj}" -x 2
Press Ctrl+C to abort.
Affect(class-cnt:1 , method-cnt:1) cost in 44 ms.
ts=2018-12-03 19:16:51; [cost=1.280502ms] result=@ArrayList[
$ watch demo.MathGame primeFactors -x 2
Press Q or Ctrl+C to abort.
Affect(class count: 1 , method count: 1) cost in 32 ms, listenerId: 5
method=demo.MathGame.primeFactors location=AtExceptionExit
ts=2021-08-31 15:22:57; [cost=0.220625ms] result=@ArrayList[
@Object[][
@Integer[-179173],
],
@MathGame[
random=@Random[java.util.Random@31cefde0],
illegalArgumentCount=@Integer[44],
],
null,
]
method=demo.MathGame.primeFactors location=AtExit
ts=2021-08-31 15:22:58; [cost=1.020982ms] result=@ArrayList[
@Object[][
@Integer[1],
],
@MathGame[
random=@Random[java.util.Random@31cefde0],
illegalArgumentCount=@Integer[44],
],
@ArrayList[
@Integer[3],
@Integer[19],
@Integer[191],
@Integer[49199],
@Integer[2],
@Integer[2],
@Integer[26947],
],
]
```
* 上面的结果里，说明函数被执行了两次，第一次结果是`location=AtExceptionExit`，说明函数抛出异常了，因此`returnObj`是null
* 在第二次结果里是`location=AtExit`，说明函数正常返回，因此可以看到`returnObj`结果是一个ArrayList
#### 观察方法入参
```bash

42
tutorials/katacoda/command-watch-cn/watch.md
View File

@ -11,7 +11,7 @@ watch 的参数比较多，主要是因为它能在 4 个不同的场景观察
|---:|:---|
|*class-pattern*|类名表达式匹配|
|*method-pattern*|方法名表达式匹配|
|*express*|观察表达式|
|*express*|观察表达式，默认值：`{params, target, returnObj}`|
|*condition-express*|条件表达式|
|[b]|在**方法调用之前**观察|
|[e]|在**方法异常之后**观察|
@ -36,29 +36,49 @@ watch 的参数比较多，主要是因为它能在 4 个不同的场景观察
### 使用参考
#### 观察方法出参和返回值
#### 观察方法出参、this对象和返回值
`watch demo.MathGame primeFactors "{params,returnObj}" -x 2`{{execute T2}}
> 观察表达式，默认值是`{params, target, returnObj}`。
`watch demo.MathGame primeFactors -x 2`{{execute T2}}
按`Q`{{execute T2}}或者`Ctrl+c`退出
```bash
$ watch demo.MathGame primeFactors "{params,returnObj}" -x 2
Press Ctrl+C to abort.
Affect(class-cnt:1 , method-cnt:1) cost in 44 ms.
ts=2018-12-03 19:16:51; [cost=1.280502ms] result=@ArrayList[
$ watch demo.MathGame primeFactors -x 2
Press Q or Ctrl+C to abort.
Affect(class count: 1 , method count: 1) cost in 32 ms, listenerId: 5
method=demo.MathGame.primeFactors location=AtExceptionExit
ts=2021-08-31 15:22:57; [cost=0.220625ms] result=@ArrayList[
@Object[][
@Integer[-179173],
],
@MathGame[
random=@Random[java.util.Random@31cefde0],
illegalArgumentCount=@Integer[44],
],
null,
]
method=demo.MathGame.primeFactors location=AtExit
ts=2021-08-31 15:22:58; [cost=1.020982ms] result=@ArrayList[
@Object[][
@Integer[1],
],
@MathGame[
random=@Random[java.util.Random@31cefde0],
illegalArgumentCount=@Integer[44],
],
@ArrayList[
@Integer[3],
@Integer[19],
@Integer[191],
@Integer[49199],
@Integer[2],
@Integer[2],
@Integer[26947],
],
]
```
* 上面的结果里，说明函数被执行了两次，第一次结果是`location=AtExceptionExit`，说明函数抛出异常了，因此`returnObj`是null
* 在第二次结果里是`location=AtExit`，说明函数正常返回，因此可以看到`returnObj`结果是一个ArrayList
#### 观察方法入参
`watch demo.MathGame primeFactors "{params,returnObj}" -x 2 -b`{{execute T2}}

44
tutorials/katacoda/command-watch-en/watch.md
View File

@ -11,7 +11,7 @@ There are four different scenarios for `watch` command, which makes it rather co
|---:|:---|
|*class-pattern*|pattern for the class name|
|*method-pattern*|pattern for the method name|
|*expression*|expression to monitor|
|*expression*|expression to watch, default value `{params, target, returnObj}`|
|*condition-expression*|condition expression to filter|
|[b]|before method being invoked|
|[e]|when method encountering exceptions|
@ -26,7 +26,7 @@ F.Y.I
3. at the *watching* point, Arthas will use the *expression* to evaluate the variables and print them out;
4. `in parameters` and `out parameters` are different since they can be modified within the invoked methods; `params` stands for `in parameters` in `-b`while `out parameters` in other *watching* points;
5. there are no `return values` and `exceptions` when using `-b`.
6. In the result of the watch command, the `location` information will be printed. There are three possible values for `location`: `AtEnter`, `AtExit`, and `AtExceptionExit`. Corresponding to the method entry, the method returns normally, and the method throws an exception.
Advanced:
* [Special usages](https://github.com/alibaba/arthas/issues/71)
@ -34,29 +34,45 @@ Advanced:
### Usage
#### Check the `out parameters` and `return value`
#### Check the `out parameters`, `this` and `return value`
`watch demo.MathGame primeFactors "{params,returnObj}" -x 2`{{execute T2}}
Press `Q`{{execute T2}} or `Ctrl+C` to abort
> The expression to watch, default value `{params, target, returnObj}`
```bash
$ watch demo.MathGame primeFactors "{params,returnObj}" -x 2
Press Ctrl+C to abort.
Affect(class-cnt:1 , method-cnt:1) cost in 44 ms.
ts=2018-12-03 19:16:51; [cost=1.280502ms] result=@ArrayList[
$ watch demo.MathGame primeFactors -x 2
Press Q or Ctrl+C to abort.
Affect(class count: 1 , method count: 1) cost in 32 ms, listenerId: 5
method=demo.MathGame.primeFactors location=AtExceptionExit
ts=2021-08-31 15:22:57; [cost=0.220625ms] result=@ArrayList[
@Object[][
@Integer[-179173],
],
@MathGame[
random=@Random[java.util.Random@31cefde0],
illegalArgumentCount=@Integer[44],
],
null,
]
method=demo.MathGame.primeFactors location=AtExit
ts=2021-08-31 15:22:58; [cost=1.020982ms] result=@ArrayList[
@Object[][
@Integer[1],
],
@MathGame[
random=@Random[java.util.Random@31cefde0],
illegalArgumentCount=@Integer[44],
],
@ArrayList[
@Integer[3],
@Integer[19],
@Integer[191],
@Integer[49199],
@Integer[2],
@Integer[2],
@Integer[26947],
],
]
```
* In the above result, the method is executed twice, the first result is `location=AtExceptionExit`, indicating that the method throws an exception, so `returnObj` is null
* In the second result is `location=AtExit`, indicating that the method returns normally, so you can see that the result of `returnObj` is an ArrayList
#### Check `in parameters`
`watch demo.MathGame primeFactors "{params,returnObj}" -x 2 -b`{{execute T2}}