diff --git a/core/src/main/java/com/taobao/arthas/core/command/monitor200/WatchCommand.java b/core/src/main/java/com/taobao/arthas/core/command/monitor200/WatchCommand.java index 3d009fc4..f4a65130 100644 --- a/core/src/main/java/com/taobao/arthas/core/command/monitor200/WatchCommand.java +++ b/core/src/main/java/com/taobao/arthas/core/command/monitor200/WatchCommand.java @@ -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; } diff --git a/site/src/site/sphinx/en/trace.md b/site/src/site/sphinx/en/trace.md index bbeb5032..ed9b5d42 100644 --- a/site/src/site/sphinx/en/trace.md +++ b/site/src/site/sphinx/en/trace.md @@ -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. diff --git a/site/src/site/sphinx/en/watch.md b/site/src/site/sphinx/en/watch.md index c95cfbfa..483d0dc4 100644 --- a/site/src/site/sphinx/en/watch.md +++ b/site/src/site/sphinx/en/watch.md @@ -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 diff --git a/site/src/site/sphinx/trace.md b/site/src/site/sphinx/trace.md index 84bb7b9f..d666452c 100644 --- a/site/src/site/sphinx/trace.md +++ b/site/src/site/sphinx/trace.md @@ -241,4 +241,17 @@ Affect(class count: 1 , method count: 1) cost in 66 ms, listenerId: 1 ``` 2. 非函数调用的指令消耗。比如 `i++`, `getfield`等指令。 -3. 在代码执行过程中,JVM可能出现停顿,比如GC,进入同步块等。 \ No newline at end of file +3. 在代码执行过程中,JVM可能出现停顿,比如GC,进入同步块等。 + +#### 使用 -v 参数打印更多信息 + +> watch/trace/monitor/stack/tt 命令都支持 `-v` 参数 + +当命令执行之后,没有输出结果。有两种可能: + +1. 匹配到的函数没有被执行 +2. 条件表达式结果是 false + +但用户区分不出是哪种情况。 + +使用 `-v`选项,则会打印`Condition express`的具体值和执行结果,方便确认。 \ No newline at end of file diff --git a/site/src/site/sphinx/watch.md b/site/src/site/sphinx/watch.md index 1deb3b13..deafd56c 100644 --- a/site/src/site/sphinx/watch.md +++ b/site/src/site/sphinx/watch.md @@ -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 diff --git a/tutorials/katacoda/command-watch-cn/watch.md b/tutorials/katacoda/command-watch-cn/watch.md index a4030b1d..93917877 100644 --- a/tutorials/katacoda/command-watch-cn/watch.md +++ b/tutorials/katacoda/command-watch-cn/watch.md @@ -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}} diff --git a/tutorials/katacoda/command-watch-en/watch.md b/tutorials/katacoda/command-watch-en/watch.md index 2231879c..8716f268 100644 --- a/tutorials/katacoda/command-watch-en/watch.md +++ b/tutorials/katacoda/command-watch-en/watch.md @@ -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}}