代码打桩

代码打桩

代码打桩，是指在 FE 或 BE 源码中插入一段代码，当程序执行到这里时，可以改变程序的变量或行为，这样的一段代码称为一个木桩。

主要用于单元测试或回归测试，用来构造正常方法无法实现的异常。

每一个木桩都有一个名称，可以随便取名，可以通过一些机制控制木桩的开关，还可以向木桩传递参数。

FE 和 BE 都支持代码打桩，打桩完后要重新编译 BE 或 FE。

木桩代码示例

FE 桩子示例代码

1. private Status foo() {
2. // dbug_fe_foo_do_nothing 是一个木桩名字，
3. // 打开这个木桩之后，DebugPointUtil.isEnable("dbug_fe_foo_do_nothing") 将会返回true
4. if (DebugPointUtil.isEnable("dbug_fe_foo_do_nothing")) {
5. return Status.Nothing;
6. }

8. do_foo_action();

10. return Status.Ok;
11. }

BE 桩子示例代码

1. void Status foo() {

3. // dbug_be_foo_do_nothing 是一个木桩名字，
4. // 打开这个木桩之后，DBUG_EXECUTE_IF 将会执行宏参数中的代码块
5. DBUG_EXECUTE_IF("dbug_be_foo_do_nothing",  { return Status.Nothing; });

7. do_foo_action();

9. return Status.Ok;
10. }

总开关

需要把木桩总开关 enable_debug_points 打开之后，才能激活木桩。默认情况下，木桩总开关是关闭的。

总开关enable_debug_points 分别在 FE 的 fe.conf 和 BE 的 be.conf 中配置。

打开木桩

打开总开关后，还需要通过向 FE 或 BE 发送 http 请求的方式，打开或关闭指定名称的木桩，只有这样当代码执行到这个木桩时，相关代码才会被执行。

API

1. POST /api/debug_point/add/{debug_point_name}[?timeout=<int>&execute=<int>]

参数

debug_point_name 木桩名字。必填。
timeout 超时时间，单位为秒。超时之后，木桩失活。默认值-1表示永远不超时。可选。
execute 木桩最大执行次数。默认值-1表示不限执行次数。可选。

Request body

无

Response

1. {
2. msg: "OK",
3. code: 0
4. }

Examples

打开木桩 foo，最多执行5次。

1. curl -X POST "http://127.0.0.1:8030/api/debug_point/add/foo?execute=5"

向木桩传递参数

激活木桩时，除了前文所述的 timeout 和 execute，还可以传递其它自定义参数。一个参数是一个形如 key=value 的 key-value 对，在 url 的路径部分，紧跟在木桩名称后，以字符 ‘?’ 开头。

API

1. POST /api/debug_point/add/{debug_point_name}[?k1=v1&k2=v2&k3=v3...]

k1=v1 k1为参数名称，v1为参数值，多个参数用&分隔。

Request body

无

Response

1. {
2. msg: "OK",
3. code: 0
4. }

Examples

假设 FE 在 fe.conf 中有配置 http_port=8030，则下面的请求激活 FE 中的木桩foo，并传递了两个参数 percent 和 duration：

1. curl -u root: -X POST "http://127.0.0.1:8030/api/debug_point/add/foo?percent=0.5&duration=3"

1. 注意：
2. 1、在 FE 或 BE 的代码中，参数名和参数值都是字符串。
3. 2、在 FE 或 BE 的代码中和 http 请求中，参数名称和值都是大小写敏感的。
4. 3、发给 FE 或 BE 的 http 请求，路径部分格式是相同的，只是 IP 地址和端口号不同。

在 FE 和 BE 代码中使用参数

激活 FE 中的木桩OlapTableSink.write_random_choose_sink并传递参数 needCatchUp 和 sinkNum:

注意：可能需要用户名和密码

1. curl -u root: -X POST "http://127.0.0.1:8030/api/debug_point/add/OlapTableSink.write_random_choose_sink?needCatchUp=true&sinkNum=3"

在 FE 代码中使用木桩 OlapTableSink.write_random_choose_sink 的参数 needCatchUp 和 sinkNum：

1. private void debugWriteRandomChooseSink(Tablet tablet, long version, Multimap<Long, Long> bePathsMap) {
2. DebugPoint debugPoint = DebugPointUtil.getDebugPoint("OlapTableSink.write_random_choose_sink");
3. if (debugPoint == null) {
4. return;
5. }
6. boolean needCatchup = debugPoint.param("needCatchUp", false);
7. int sinkNum = debugPoint.param("sinkNum", 0);
8. ...
9. }

激活 BE 中的木桩TxnManager.prepare_txn.random_failed并传递参数 percent:

1. curl -X POST "http://127.0.0.1:8040/api/debug_point/add/TxnManager.prepare_txn.random_failed?percent=0.7

在 BE 代码中使用木桩 TxnManager.prepare_txn.random_failed 的参数 percent：

1. DBUG_EXECUTE_IF("TxnManager.prepare_txn.random_failed",
2. {if (rand() % 100 < (100 * dp->param("percent", 0.5))) {
3. LOG_WARNING("TxnManager.prepare_txn.random_failed random failed");
4. return Status::InternalError("debug prepare txn random failed");
5. }}
6. );

关闭木桩

API

1. POST /api/debug_point/remove/{debug_point_name}

参数

debug_point_name 木桩名字。必填。

Request body

无

Response

1. {
2. msg: "OK",
3. code: 0
4. }

Examples

关闭木桩foo。

1. curl -X POST "http://127.0.0.1:8030/api/debug_point/remove/foo"

清除所有木桩

API

1. POST /api/debug_point/clear

Request body

无

Response

1. {
2. msg: "OK",
3. code: 0
4. }

Examples

清除所有木桩。

1. curl -X POST "http://127.0.0.1:8030/api/debug_point/clear"

在回归测试中使用木桩

提交PR时，社区 CI 系统默认开启 FE 和 BE 的enable_debug_points配置。

回归测试框架提供方法函数来开关指定的木桩，它们声明如下：

1. // 打开木桩，name 是木桩名称，params 是一个key-value列表，是传给木桩的参数
2. def enableDebugPointForAllFEs(String name, Map<String, String> params = null);
3. def enableDebugPointForAllBEs(String name, Map<String, String> params = null);
4. // 关闭木桩，name 是木桩的名称
5. def disableDebugPointForAllFEs(String name);
6. def disableDebugPointForAllFEs(String name);

需要在调用测试 action 之前调用 enableDebugPointForAllFEs() 或 enableDebugPointForAllBEs() 来开启木桩，这样执行到木桩代码时，相关代码才会被执行，然后在调用测试 action 之后调用 disableDebugPointForAllFEs() 或 disableDebugPointForAllBEs() 来关闭木桩。

并发问题

FE 或 BE 中开启的木桩是全局生效的，同一个 Pull Request 中，并发跑的其它测试，可能会受影响而意外失败。为了避免这种情况，我们规定，使用木桩的回归测试，必须放在 regression-test/suites/fault_injection_p0 目录下，且组名必须设置为 nonConcurrent，社区 CI 系统对于这些用例，会串行运行。

Examples

1. // 测试用例的.groovy 文件必须放在 regression-test/suites/fault_injection_p0 目录下，
2. // 且组名设置为 'nonConcurrent'
3. suite('debugpoint_action', 'nonConcurrent') {
4. try {
5. // 打开所有FE中，名为 "PublishVersionDaemon.stop_publish" 的木桩
6. // 传参数 timeout
7. // 与上面curl调用时一样，execute 是执行次数，timeout 是超时秒数
8. GetDebugPoint().enableDebugPointForAllFEs('PublishVersionDaemon.stop_publish', [timeout:1])
9. // 打开所有BE中，名为 "Tablet.build_tablet_report_info.version_miss" 的木桩
10. // 传参数 tablet_id, version_miss 和 timeout
11. GetDebugPoint().enableDebugPointForAllBEs('Tablet.build_tablet_report_info.version_miss',
12. [tablet_id:'12345', version_miss:true, timeout:1])

14. // 测试用例，会触发木桩代码的执行
15. sql """CREATE TABLE tbl_1 (k1 INT, k2 INT)
16. DUPLICATE KEY (k1)
17. DISTRIBUTED BY HASH(k1)
18. BUCKETS 3
19. PROPERTIES ("replication_allocation" = "tag.location.default: 1");
20. """
21. sql "INSERT INTO tbl_1 VALUES (1, 10)"
22. sql "INSERT INTO tbl_1 VALUES (2, 20)"
23. order_qt_select_1_1 'SELECT * FROM tbl_1'

25. } finally {
26. GetDebugPoint().disableDebugPointForAllFEs('PublishVersionDaemon.stop_publish')
27. GetDebugPoint().disableDebugPointForAllBEs('Tablet.build_tablet_report_info.version_miss')
28. }
29. }