> 方法执行数据观测

让你能方便的观察到指定方法的调用情况。能观察到的范围为：`返回值`{{}} 、`抛出异常`{{}} 、`入参`{{}} ，通过编写 OGNL 表达式进行对应变量的查看。

### 参数说明

watch 的参数比较多，主要是因为它能在 4 个不同的场景观察对象

|            参数名称 | 参数说明                                              |
| ------------------: | :---------------------------------------------------- |
|     _class-pattern_ | 类名表达式匹配                                        |
|    _method-pattern_ | 方法名表达式匹配                                      |
|           _express_ | 观察表达式，默认值：`{params, target, returnObj}`{{}} |
| _condition-express_ | 条件表达式                                            |
|                 [b] | 在**方法调用之前**观察                                |
|                 [e] | 在**方法异常之后**观察                                |
|                 [s] | 在**方法返回之后**观察                                |
|                 [f] | 在**方法结束之后**(正常返回和异常返回) 观察           |
|                 [E] | 开启正则表达式匹配，默认为通配符匹配                  |
|                [x:] | 指定输出结果的属性遍历深度，默认为 1                  |

[watch 命令文档](https://arthas.aliyun.com/doc/watch.html)

这里重点要说明的是观察表达式，观察表达式的构成主要由 ognl 表达式组成，所以你可以这样写`"{params,returnObj}"`{{}} ，只要是一个合法的 ognl 表达式，都能被正常支持。

观察的维度也比较多，主要体现在参数 `advice`{{}} 的数据结构上。`Advice`{{}} 参数最主要是封装了通知节点的所有信息。请参考[表达式核心变量](advice-class.md)中关于该节点的描述。

- 特殊用法请参考：[https://github.com/alibaba/arthas/issues/71](https://github.com/alibaba/arthas/issues/71)
- OGNL 表达式官网：[https://commons.apache.org/proper/commons-ognl/language-guide.html](https://commons.apache.org/proper/commons-ognl/language-guide.html)

**特别说明**：

- watch 命令定义了 4 个观察事件点，即 `-b`{{}} 方法调用前，`-e`{{}} 方法异常后，`-s`{{}} 方法返回后，`-f`{{}} 方法结束后
- 4 个观察事件点 `-b`{{}} 、`-e`{{}} 、`-s`{{}} 默认关闭，`-f`{{}} 默认打开，当指定观察点被打开后，在相应事件点会对观察表达式进行求值并输出
- 这里要注意`方法入参`{{}} 和`方法出参`{{}} 的区别，有可能在中间被修改导致前后不一致，除了 `-b`{{}} 事件点 `params`{{}} 代表方法入参外，其余事件都代表方法出参
- 当使用 `-b`{{}} 时，由于观察事件点是在方法调用前，此时返回值或异常均不存在

### 使用参考

#### 观察方法出参、this 对象和返回值

> 观察表达式，默认值是`{params, target, returnObj}`{{}} 。

`watch demo.MathGame primeFactors -x 2`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

- 从运行结果里，说明函数被执行了两次，第一次结果是`location=AtExceptionExit`{{}} ，说明函数抛出异常了，因此`returnObj`{{}} 是 null
- 在第二次结果里是`location=AtExit`{{}} ，说明函数正常返回，因此可以看到`returnObj`{{}} 结果是一个 ArrayList

#### 观察方法入参

`watch demo.MathGame primeFactors "{params,returnObj}" -x 2 -b`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

- 对比前一个例子，返回值为空（事件点为方法执行前，因此获取不到返回值）

#### 同时观察方法调用前和方法返回后

`watch demo.MathGame primeFactors "{params,target,returnObj}" -x 2 -b -s -n 2`{{execute T2}}

- 参数里`-n 2`{{}} ，表示只执行两次
- 这里输出结果中，第一次输出的是方法调用前的观察表达式的结果，第二次输出的是方法返回后的表达式的结果
- 结果的输出顺序和事件发生的先后顺序一致，和命令中 `-s -b`{{}} 的顺序无关

#### 调整`-x`{{}} 的值，观察具体的方法参数值

`watch demo.MathGame primeFactors "{params,target}" -x 3`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

- `-x`{{}} 表示遍历深度，可以调整来打印具体的参数和结果内容，默认值是 1。

#### 条件表达式的例子

`watch demo.MathGame primeFactors "{params[0],target}" "params[0]<0"`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

- 只有满足条件的调用，才会有响应。
- `watch-express`{{}} 单个值可以不加'{}'，多个值需要加'{a,b,c}'。
- `condition-express`{{}} 不能加'{}'，可以使用逗号分隔子表达式，取表达式最后一个值来判断。
- 如果 watch 的方法存在同名的其它重载方法，可以通过下面的办法进行过滤：

- 根据参数类型进行过滤

`watch demo.MathGame primeFactors '{params, params[0].class.name}' 'params[0].class.name == "java.lang.Integer"'`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

- 根据参数个数进行过滤

`watch demo.MathGame primeFactors '{params, params.length}' 'params.length==1'`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

#### 观察异常信息的例子

`watch demo.MathGame primeFactors "{params[0],throwExp}" -e -x 2`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

- `-e`{{}} 表示抛出异常时才触发
- express 中，表示异常信息的变量是`throwExp`{{}}

根据异常类型或者 message 进行过滤：

`watch demo.MathGame primeFactors '{params, throwExp}' '#msg=throwExp.toString(), #msg.contains("IllegalArgumentException")' -e -x 2`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

#### 按照耗时进行过滤

`watch demo.MathGame primeFactors '{params, returnObj}' '#cost>200' -x 2`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

- `#cost>200`{{}} (单位是`ms`{{}} ) 表示只有当耗时大于 200ms 时才会输出，过滤掉执行时间小于 200ms 的调用

#### 观察当前对象中的属性

`watch demo.MathGame primeFactors 'target'`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出

如果想查看方法运行前后，当前对象中的属性，可以使用`target`{{}} 关键字，代表当前对象  
然后使用`target.field_name`{{}} 访问当前对象的某个属性

`watch demo.MathGame primeFactors 'target.illegalArgumentCount'`{{execute T2}}

按 `Q`{{exec interrupt}} 或者 `Ctrl+c`{{exec interrupt}} 退出