add md shell, update go

.gitignore

@@ -10,6 +10,14 @@ example/example
 example/example.test
 example/nohup.out
 example/replayer/replayer
+example/replayer/replayer.test
+example/replayer/example.test
+example/replayer/example
+example/replayer/sut.pid
+example/replayer/sut.log
+example/replayer/gocov
+example/replayer/gocov-html
+example/replayer/nohup.out
 
 # agent
 recorder-agent/agent

doc/replayer/README.md

@@ -1,7 +1,11 @@
 # 流量回放
 
+<br>
+
 流量回放，即基于录制的流量在线下对改造后的代码进行回放，以验证线下代码逻辑的正确性。其中，流量录制可以根据需求，录制线上机器的真实流量，或者录制本地机器的测试流量。
 
+<br>
+
 ### 一、名词解释
 * **SUT**: System Under Test, 在这里特指被测业务服务。目前仅支持对外提供HTTP接口的SUT回放。
 * **Inbound**: 指SUT对外提供的HTTP接口的请求和响应，即Inbound Request/Response。
@@ -13,17 +17,42 @@
 * **噪音**: 即在Inbound Response对比和Outbound Request匹配过程里，出现的不影响回放结果和匹配度的diff字段，如时间戳。Agent回放结果页支持上报噪音，方便再次回放时精确回放结果。
 * **DSL**: 特指ElasticSearch的查询DSL。Agent首页支持上报流量查询DSL，方便后面直接复用。
 
+<br>
+
 ### 二、回放接入
 
 回放前提：已经完成流量录制。[录制接入文档](../recorder/README.md)
 
-##### 1. 配置并启动SUT
+对于服务启动阶段有TCP请求的SUT，如初始化连接池等，推荐 服务启动顺序：
+* 先启动Agent 
+* 再启动SUT
+
+##### 1. 配置并启动Agent
+
+> 温馨提示：Agent默认配置的是 **[本地回放](#4本地回放)**，即 仅依赖本地配置文件的回放。
+* 如需 读取录制的线上流量，只需根据[回放Agent配置](./replayer-conf.md#5-es_url)修改es_url字段即可；
+* 如需 读取上报到自有服务的噪音或DSL，只需根据[回放Agent配置](./replayer-conf.md#4-http_api)修改http_api字段即可；
+* 如需 新增本地回放模块，请参考[本地回放接入](./replayer-local.md)。
+
+首先，确保本地存在go环境(官方或定制版均可，且版本无要求), 并根据本地go版本选择go mod或glide来安装sharingan的依赖。
+```shell script
+glide install || go mod download
+```
+然后编译并启动Agent：
+```shell script
+cd ./replayer-agent && go build && nohup ./replayer-agent >> run.log 2>&1 &
+```
+> Agent一键安装和启动 [脚本](../../replayer-agent/control.sh) 及其 [使用方法](./replayer-agent.md)
+
+<br>
+
+##### 2. 配置并启动SUT
 
 > 需要使用定制的golang，并通过指定tag来编译 引入回放包的SUT代码。
 
 首先，配置定制版golang环境，目前支持go1.10、go1.11、go1.12、go1.13。亦可参考：[golang安装](https://github.com/didichuxing/sharingan-go)
 ```shell script
-curl https://raw.githubusercontent.com/didichuxing/sharingan-go/recorder/install/go1.10 | sh
+curl https://github.com/didichuxing/sharingan-go/raw/recorder/install/go1.10 | sh
 && export GOROOT=/tmp/recorder-go1.10
 && export PATH=$GOROOT/bin:$PATH
 ```
@@ -36,29 +65,13 @@ import _ "github.com/didichuxing/sharingan/replayer"
 最后，编译并启动SUT服务。
 ```shell script
 go build -tags="replayer" -gcflags="all=-N -l"
-&& nohup ./$project 2>&1 &
+&& nohup ./$project >> run.log 2>&1 &
 ```
-> SUT一键接入&&启动脚本([./example/replayer/sut_replayer.sh](../../example/replayer/sut_replayer.sh))及[使用方法](./replayer-sut.md)
+> SUT一键接入和启动 [脚本](../../example/replayer/sut_replayer.sh) 及其 [使用方法](./replayer-sut.md)
 
-##### 2. 配置并启动Agent
+至此，浏览器打开 [http://127.0.0.1:8998](http://127.0.0.1:8998) 或 local_ip 即可开始回放啦~
 
-> 温馨提示：Agent默认配置的是 **[本地回放](#4本地回放)**，即 仅依赖本地配置文件的回放。
-* 如需 读取录制的线上流量，只需根据[回放Agent配置](./replayer-conf.md#5-es_url)修改es_url字段即可；
-* 如需 读取上报到自有服务的噪音或DSL，只需根据[回放Agent配置](./replayer-conf.md#4-http_api)修改http_api字段即可；
-* 如需 新增本地回放模块，请参考[本地回放接入](./replayer-local.md)。
-
-首先，确保本地存在go环境(官方或定制版均可，且版本无要求), 并根据本地go版本选择go mod或glide来安装sharingan的依赖。
-```shell script
-glide install || go mod download
-```
-然后编译并启动Agent：
-```shell script
-cd ./replayer-agent && go build && nohup ./replayer-agent 2>&1 &
-```
-
-至此，浏览器打开 [http://127.0.0.1:8998](http://127.0.0.1:8998) 即可开始回放啦~
-
-> Agent一键安装&&启动脚本([./replayer-agent/control.sh](../../replayer-agent/control.sh))及[使用方法](./replayer-agent.md)
+<br>
 
 ### 三、使用手册
 
@@ -79,7 +92,7 @@ cd ./replayer-agent && go build && nohup ./replayer-agent 2>&1 &
 
 ##### 2.覆盖率统计
 
-流量回放不仅支持上面[接入流程-配置并启动SUT](#1-配置并启动sut)展示的普通回放接入，还支持覆盖率统计方式的回放接入。
+流量回放不仅支持上面[接入流程-配置并启动SUT](#2-配置并启动sut)展示的普通回放接入，还支持覆盖率统计方式的回放接入。
 
 [覆盖率统计接入](./replayer-codecov.md)
 
@@ -99,5 +112,7 @@ Agent默认配置的本地回放，如需修改，请参考：[回放Agent配置
 ### 四、常见问题
 [常见问题及排查](./guide/troubleshoot.md)
 
+[交流群](./guide/troubleshoot.md#交流群)
+
 ### 五、回放原理
-[回放原理详解](./replayer-theory.md)
+[回放原理详解](./replayer-theory.md)

doc/replayer/conf/http_api.md

@@ -1,14 +1,15 @@
 ### 噪音/DSL/模块_http接口说明
 
-回放时，噪音、DSL 根据 [本地回放](../README.md#4本地回放) 和 非本地回放 的不同，分别上报到不同的地方；而模块信息也会读取自不同的来源：[回放模块配置](./conf/moduleinfo.md)。
+<br>
+
+回放时，噪音、DSL 根据 [本地回放](../README.md#4本地回放) 和 非本地回放 的不同，分别上报到不同的地方；模块信息也会读取自不同的来源：[回放模块配置](./conf/moduleinfo.md)。
 
 * 本地回放：噪音 上报到本机 [conf/noise/](../../../replayer-agent/conf/noise) 目录下，DSL 上报到本机 [conf/dsl/](../../../replayer-agent/conf/dsl) 目录下，模块信息读取自本地配置。
 * 非本地回放：噪音、DSL 上报到 [conf/app.toml](../../../replayer-agent/conf/app.toml) 下 [http_api]小节 配置的http接口。模块信息也读取自该配置接口。
 
-回放Agent默认配置的是本地回放，因此，对于想将 噪音、DSL、模块信息 存入数据库，而非本地配置文件的同学，可以参考下面的接口说明，实现接口即可。
-
+<br>
 
-下面逐个接口说明:
+回放Agent默认配置的是本地回放；对于想将 噪音、DSL、模块信息存入数据库的同学，请仔细阅读下面接口说明。
 > 温馨提示：
 >
 > 接口实现 只要字段名和字段类型符合接口说明即可，**至于字段的具体值无需担心，因为所有的值都会通过前端js处理后传给后端，比如dsl字段、noise字段等**。
@@ -39,6 +40,8 @@
 | errno | int | 错误码，0 成功，非0 失败 |
 | errmsg | string | 错误信息 |
 
+<br>
+
 ##### 2. dsl_get
 
 接口: http://{{your_domain}}/dsl?project=%s
@@ -63,6 +66,8 @@
 | project | string | 被测模块名 |
 | addTime | string | 添加时间 |
 
+<br>
+
 ##### 3. noise_push
 
 接口: http://{{your_domain}}/noise
@@ -88,6 +93,8 @@
 | errno | int | 错误码，0 成功，非0 失败 |
 | errmsg | string | 错误信息 |
 
+<br>
+
 ##### 4. noise_del
 
 接口: http://{{your_domain}}/noise/del
@@ -109,6 +116,8 @@
 | errno | int | 错误码，0 成功，非0 失败 |
 | errmsg | string | 错误信息 |
 
+<br>
+
 ##### 5. noise_get
 
 接口: http://{{your_domain}}/noise
@@ -136,6 +145,8 @@
 | addTime | string | 添加时间 |
 | user | string | 上报用户 |
 
+<br>
+
 ##### 6. module_info
 
 接口: http://{{your_domain}}/platform/module?per=1000
@@ -160,16 +171,24 @@
 | Module说明 |  |  |
 | :-----| :-----| :-----|
 | name | string | 接入模块名，即project |
-| data | string | []KV类型数组的json串 |
+| data | string | []KV类型数组的json串，存储模块详细信息 |
+
+> 温馨提示：
+>
+> name尽量与编译后的$binName保持一致。如果存在冲突，可以增加前缀'\*-'，即\*-$binName。
+>
+> 如果name形如'\*a-b-c'，则尽量保证c具有可识别性，因为，[覆盖率统计回放](../replayer-codecov.md#1-覆盖率报告)会通过 *c* 来获取SUT进程信息并重启SUT。
 
 | KV说明 |  |  |
 | :-----| :-----| :-----|
-| key | string | 某项配置信息名，如git |
-| value | string | 具体配置值，如[email protected] |
+| key | string | 与模块相关的一些信息，如监听地址listen-addr等 |
+| value | string | 与key对应的具体值 |
 
 目前KV类型中key支持的具体值有：
 * context：必选，录制机器的地址，与录制流量的Context字段对应，以区分不同模块。一般一个模块找一台机器录制流量即可。
 
 * listen-addr：必选，SUT的监听地址，一般为127.0.0.1:xxxx。
 
 * department：可选，模块所属部门，默认空(则为default部门)。若非空，在非本地回放时，会按部门字段读取es_url地址。es_url配置可详见：[回放Agent配置](../replayer-conf.md#5-es_url)
+
+非本地回放时，Agent只用到上面三个key值，如果业务方想在该接口顺便存储模块其他信息，只需扩充[]KV即可。

doc/replayer/conf/moduleinfo.md

@@ -1,10 +1,13 @@
 ### 回放模块配置
 
+<br>
+
 回放时，被测模块的基本信息 根据 [本地回放](../README.md#4本地回放) 和 非本地回放 的不同，分别读取自不同的来源。
 
 * 本地回放：读取自本地配置文件 [conf/moduleinfo.json](../../../replayer-agent/conf/moduleinfo.json) 
 * 非本地回放：读取自 [conf/app.toml](../../../replayer-agent/conf/app.toml) 下 [http_api]小节module_info字段 配置的http接口。接口设计详见[http接口说明](./http_api.md#6-module_info)
 
+<br>
 
 下面主要针对 conf/moduleinfo.json 内的配置字段进行解释说明。
 
@@ -14,31 +17,34 @@
   "data": [
     {
       "name":"example",
-      "data":"[{\"key\":\"context\",\"value\":\"localhost\"},{\"key\":\"listen-addr\",\"value\":\"127.0.0.1:9999\"},{\"key\":\"department\",\"value\":\"Biz\"}]"
+      "data":"[{\"key\":\"listen-addr\",\"value\":\"127.0.0.1:9999\"}]"
     }
   ]
 }
 ```
+<br>
 
 ##### 2. 配置说明
 
 | moduleinfo.json字段说明 |  |
 | :-----| :-----|
-| data | []Module, Module类型的数组 |
+| data | []Module, Module类型的数组，数组每个值代表一个模块 |
 
 | Module类型说明 | 类型 | 说明 |
 | :-----| :----- | :----- |
 | name | string | 模块名 |
-| data | string | []KV类型的json串 |
+| data | string | []KV类型的json串，存储模块详细信息 |
+
+> 温馨提示：
+>
+> name尽量与编译后的$binName保持一致。如果存在冲突，可以增加前缀'\*-'，即\*-$binName。
+>
+> 如果name形如'\*a-b-c'，则尽量保证c具有可识别性，因为，[覆盖率统计回放](../replayer-codecov.md#1-覆盖率报告)会通过 *c* 来获取SUT进程信息并重启SUT。
 
 | KV类型说明 | 类型 | 说明 |
 | :-----| :----- | :----- |
-| key | string | 与模块相关的一些数据，如监听地址listen-addr等 |
-| value | string | 与key对应的value值 |
-
-目前KV类型中key支持的具体值有：
-* context：必选，录制机器的地址，与录制流量的Context字段对应，以区分不同模块。一般一个模块找一台机器录制流量即可。
+| key | string | 与模块相关的一些信息，如监听地址listen-addr等 |
+| value | string | 与key对应的具体值 |
 
+本地回放时，KV类型中key只需支持一个"listen-addr"即可：
 * listen-addr：必选，SUT的监听地址，一般为127.0.0.1:xxxx。
-
-* department：可选，模块所属部门，默认空(则为default部门)。若非空，在非本地回放时，会按部门字段读取es_url地址。es_url配置可详见：[回放Agent配置](../replayer-conf.md#5-es_url)

doc/replayer/guide/replay.md

@@ -1,3 +1,75 @@
 ### 流量回放指南
 
-即将更新~
+<br>
+
+流量回放指南 可以帮助对我们进一步了解回放结果页的流量状态及字段，加深我们对回放结果的理解，提升问题定位的能力。
+
+<br>
+下面逐个介绍：
+
+##### 1. 查看接口返回
+点击下图1的"运行"后，会进入图2的流量回放结果页。
+![guide_replay_run](../../images/guide_replay_run.png)
+
+下图2的流量回放结果页，第一条请求，即Inbound请求，标注为"主请求"。其余请求均为Outbound请求。
+![guide_replay_response](../../images/guide_replay_response.png)
+
+主请求里的 'Testing Response'，就是SUT针对Inbound请求的返回结果，包括header头和body体。
+
+![guide_replay_outbound](../../images/guide_replay_outbound.png)
+
+> 注意：
+>
+>对比上图2和上图3，只有Inbound请求的'O==T Diff' tab给的是Response的diff结果。 所有Outbound请求的'O==T Diff' tab给的是Request的diff结果。
+
+<br>
+
+##### 2. 定位失败原因
+
+回放Agent采用了非常严格的测试标准，只要有任何diff或者异常都会显示回放失败，目的是为了让大家能够发现隐藏问题
+
+对于回放失败的结果，还可以细分如下：
+
+> 状态1：存在diff
+
+![guide_replay_diff](../../images/guide_replay_diff.png)
+
+如上图，点击飘红的行，存在飘红的字段。
+
+根据代码可以区分出这个是一个“噪音”(每次都是随机数)，可以点击"上报噪音"消除噪音，被消除噪音在下次回放时就消失了。
+
+<br>
+
+> 状态2：missing
+
+![guide_replay_missing](../../images/guide_replay_missing.png)
+
+出现上图情况，是因为被测代码缺少一条请求，这个时候就要确认是否有删除或者改动代码有问题。亦可详见：[常见问题及排查](./troubleshoot.md#5-部分outbound匹配失败ot-diff没有diff) 第5条。
+
+<br>
+
+> 状态3：not matched
+
+![guide_replay_notmatch](../../images/guide_replay_notmatch.png)
+
+出现上图情况，是因为被测代码发出了线上流量没有的请求，匹配不到，所以可能也是代码中加入了新的逻辑。亦可详见：[常见问题及排查](./troubleshoot.md#5-部分outbound匹配失败ot-diff没有diff) 第5条。
+
+<br>
+
+更多问题，请详见 [常见问题及排查](./troubleshoot.md) 手册，及里面的 **[Sharingan交流群](./troubleshoot.md#交流群)**。
+
+<br>
+
+##### 3. 格式化
+> 支持json格式化
+
+选中json代码片段，当松开鼠标按钮的时候就会将其格式化显示。如下图所示
+
+![guide_replay_json1](../../images/guide_replay_json1.png)
+
+<br>
+
+> 支持unicode编码转换
+
+选中带引号的unicode编码片段即可。因为 带引号的片段会当成json格式处理，自动会进行编码转换
+![guide_replay_json2](../../images/guide_replay_json2.png)