nettrace: add doc and man for --trace-stack

Signed-off-by: Menglong Dong <imagedong@tencent.com>

Author: menglongdong

README.md

@@ -164,6 +164,7 @@ Usage:
     --monitor        enable 'monitor' mode
     --drop-stack     print the kernel function call stack of kfree_skb
     --min-latency       the minial time to live of the skb
+    --trace-stack    print call stack for traces or group
 
     -v               show log information
     --debug          show debug information
@@ -187,8 +188,9 @@ Usage:
 - `monitor`：启用监控模式。一种轻量化的实时监控系统中网络异常的模式（对内核版本有一定要求）。
 - `hooks`：结合netfilter做的适配，详见下文
 - `drop`：进行系统丢包监控，取代原先的`droptrace`
-- `drop-stack`: 打印kfree_skb内核函数的调用堆栈
+- `drop-stack`: 打印kfree_skb内核函数的调用堆栈，等价于`--trace-stack kfree_skb`
 - `min-latency`：根据报文的寿命进行过滤，仅打印处理时长超过该值的报文，单位为ms。该参数仅在默认和`diag`模式下可用。
+- `trace-stack`：指定需要进行堆栈打印的内核函数，可以指定多个，用“,”分隔。出于性能考虑，启用堆栈打印的内核函数不能超过16个。
 
 下面我们首先来看一下默认模式下的工具使用方法。
 
@@ -351,6 +353,76 @@ begin trace...
 [66.740110] [consume_skb         ] ICMP: 192.168.122.8 -> 192.168.122.1 ping reply, seq: 1, id: 32535
 ```
 
+#### 3.1.6 堆栈打印
+
+可以通过`--trace-stack`来指定需要进行内核堆栈打印的`traces`，使用方式与`--trace`完全一致。出于性能的考虑，目前启用堆栈打印的内核函数不能超过16个。基本用法：
+
+```shell
+$ sudo ./nettrace -p icmp --trace-stack consume_skb,icmp_rcv
+begin trace...
+***************** ffff88882cafd200,ffff88882cafdc00 ***************
+[2846531.810609] [nf_hook_slow        ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956 *ipv4 in chain: OUTPUT*
+[2846531.810612] [ip_output           ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810613] [nf_hook_slow        ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956 *ipv4 in chain: POST_ROUTING*
+[2846531.810615] [ip_finish_output    ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810617] [ip_finish_output2   ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810619] [__dev_queue_xmit    ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810621] [dev_hard_start_xmit ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956 *skb is successfully sent to the NIC driver*
+[2846531.810623] [enqueue_to_backlog  ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810630] [__netif_receive_skb_core.constprop.0] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810632] [ip_rcv              ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810634] [ip_rcv_core         ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810635] [nf_hook_slow        ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956 *ipv4 in chain: PRE_ROUTING*
+[2846531.810637] [ip_local_deliver    ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810639] [nf_hook_slow        ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956 *ipv4 in chain: INPUT*
+[2846531.810640] [nft_do_chain        ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956 *iptables table:filter, chain:INPUT*
+[2846531.810642] [ip_local_deliver_finish] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810644] [skb_clone           ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810649] [icmp_rcv            ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+Call Stack:
+    -> icmp_rcv+0x1
+    -> ip_local_deliver_finish+0x7f
+    -> ip_local_deliver+0xea
+    -> ip_rcv+0x16d
+    -> __netif_receive_skb_one_core+0x89
+    -> process_backlog+0xa9
+    -> __napi_poll+0x2e
+    -> net_rx_action+0x28f
+    -> __do_softirq+0xfb
+    -> do_softirq+0xa7
+    -> __local_bh_enable_ip+0x79
+    -> ip_finish_output2+0x170
+    -> __ip_finish_output+0xae
+    -> ip_finish_output+0x36
+    -> ip_output+0x73
+    -> ip_push_pending_frames+0xab
+    -> raw_sendmsg+0x651
+    -> inet_sendmsg+0x6e
+    -> sock_sendmsg+0x60
+    -> __sys_sendto+0x10a
+    -> __x64_sys_sendto+0x24
+    -> do_syscall_64+0x3f
+    -> entry_SYSCALL_64_after_hwframe+0x72
+
+[2846531.810651] [ping_rcv            ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810653] [ping_lookup.isra.0  ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810654] [kfree_skb           ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+[2846531.810659] [consume_skb         ] ICMP: 127.0.0.1 -> 127.0.0.1 ping reply, seq: 3, id: 51956
+Call Stack:
+    -> consume_skb+0xb8
+    -> consume_skb+0xb8
+    -> skb_free_datagram+0x11
+    -> raw_recvmsg+0xb2
+    -> inet_recvmsg+0x11d
+    -> sock_recvmsg+0x6e
+    -> ____sys_recvmsg+0x90
+    -> ___sys_recvmsg+0x7c
+    -> __sys_recvmsg+0x60
+    -> __x64_sys_recvmsg+0x1d
+    -> do_syscall_64+0x3f
+    -> entry_SYSCALL_64_after_hwframe+0x72
+```
+
 ### 3.2 诊断模式
 
 使用方式与上面的一致，加个`diag`参数即可使用诊断模式。上文的生命周期模式对于使用者的要求比较高，需要了解内核协议栈各个函数的用法、返回值的意义等，易用性较差。诊断模式是在生命周期模式的基础上，提供了更加丰富的信息，使得没有网络开发经验的人也可进行复杂网络问题的定位和分析。

docs/develop.md

@@ -81,19 +81,19 @@ trace.yaml -- gen_trace.py                                      |
 
 这个配置文件是项目的核心配置，里面按照`yaml`格式保存了所有的支持的内核函数，按照树状图的结构来配置的。在树状图中，所有的叶节点表示的都是trace（跟踪点，内核函数或者tracepoint），非叶节点代表的都是网络模块，也可以理解为目录。
 
-网络模块（目录）的格式如下：
+**网络模块（目录）格式**：
 
 - name：名称
 - desc：一段描述
 - visual：是否对用户可见，默认true
 - children：子目录，或者当前目录下的traces
 
-trace的格式：
+**trace的格式**：
 
-- name：在未指定target的情况下，这个名称就是要跟踪的内核函数的名称。其格式为：内核函数名称:skb:sock，其中skb指的是skb参数在该内核函数参数中的位置，从0开始；sock代表sk在该内核函数中的位置（非必须）。如果只跟踪skb，那只需要写成：function:skb的格式即可。
-  注意：function:skb是一种简写，这样写完就不需要写skb了，不然要提供skb字段才行
+- name：在未指定target的情况下，这个名称就是要跟踪的内核函数的名称。
 - target：当前trace针对的内核函数。在name和内核函数不同的情况下，可以通过target来指定需要跟踪的内核函数。
 - skb：skb参数在该内核函数参数中的位置，从0开始
+- sock：sk参数在该内核函数参数中的位置，从0开始（仅用作--sock模式）
 - tp：tracepoint类型需要写的，tracepoint的位置。格式：dir:tracepoint
 - analyzer：解析器。该参数用于指定诊断模式下分析当前函数采集到的数据的诊断器，默认不进行特殊的数据格式检查和处理。
 - rules：定义诊断模式下的规则。规则有三种级别，分别是：
@@ -105,6 +105,16 @@ trace的格式：
   - msg：当命中规则后给出的信息
   - adv：诊断建议，一般用于`error`级别的规则。
 
+**简写方式**：
+
+可以在`name`中指定skb或者sk的索引，其格式为：内核函数名称:skb/sock，其中skb指的是skb参数在该内核函数参数中的位置，从0开始；sock代表sk在该内核函数中的位置（非必须，--sock模式下的跟踪点）。如果只跟踪skb，那只需要写成：function:skb的格式即可。如果当前定义的trace只包含`name`，那么可以进一步对其进行简化，只需要将trace定义为字符串即可，如下所示：
+
+```yaml
+- name: ip_rcv:0 # 定义了一个trace对象，跟踪的是内核函数ip_rcv，其中skb在这个函数参数中的索引为0
+- ip_rcv:0 # 使用字符串来定义trace，作用和上面的一样
+- name: inet_listen/0 # 定义了一个trace对象，跟踪的是内核函数inet_listen，其中sock在这个函数参数中的索引为0，该trace仅在sock模式下有效。
+```
+
 ### 3.2 诊断器开发
 
 常规场景下，如果我们有需要跟踪的内核函数或者场景，只需要在`trace.yaml`中增加对应的`trace`即可。如果需要增加额外的数据采集和分析能力，就需要增加自定义`诊断器`了。新增诊断器所要做的修改包括以下内容：

script/bash-completion.sh

@@ -1,2 +1,2 @@
-complete -W '-s --saddr -d --daddr --addr -p -D --dport -S --sport -P --port --pid --netns --netns-current -t --trace -v --detail --debug --bpf-debug --ret --basic --diag --diag-quiet --diag-keep --sock --min-latency --date --drop --drop-stack --hooks --monitor -h --help' nettrace
+complete -W '-s --saddr -d --daddr --addr -p -D --dport -S --sport -P --port --pid --netns --netns-current -t --trace -v --detail --debug --bpf-debug --ret --basic --diag --diag-quiet --diag-keep --sock --min-latency --date --drop --drop-stack --hooks --monitor --trace-stack -h --help' nettrace
 complete -W '-h -s -d --addr -p --dport --sport --port -t -v --detail --stack --stack-tracer --timeline -c --ret --skb-mode --force-stack --tcp-flags -o --output' nettrace-legacy

script/zh_CN/nettrace.8

@@ -94,11 +94,15 @@ nettrace \- Linux系统下的网络报文跟踪、网络问题诊断工具
 进行系统丢包监控，取代原先的\fB\fCdroptrace\fR
 .TP
 \fB\fC\-\-drop\-stack\fR
-打印kfree_skb内核函数的调用堆栈
+打印kfree\fIskb内核函数的调用堆栈，等价于`\-\-trace\-stack kfree\fPskb`
 .TP
-\fB\fC\-\-min\-latency\fR
+\fB\fC\-\-min\-latency\fR \fIlatency in ms\fP
 根据报文的寿命进行过滤，仅打印处理时长超过该值的报文，单位为ms。该参数仅在默认和\fB\fCdiag\fR模式下可用。
 .TP
+\fB\fC\-\-trace\-stack\fR \fItraces\fP
+指定需要进行堆栈打印的内核函数，可以指定多个，用“,”分隔。出于性能考虑，启用堆栈打印的
+内核函数不能超过16个。用法和格式与\fB\fC\-\-trace\fR完全一致。
+.TP
 \fB\fC\-v\fR
 显示程序启动的日志信息
 .TP
@@ -115,6 +119,9 @@ nettrace \- Linux系统下的网络报文跟踪、网络问题诊断工具
 .TP
 显示详细信息：
 \fInettrace \-p icmp \-s 192.168.1.8 \-\-detail\fP
+.TP
+打印堆栈：
+\fInettrace \-p icmp \-s 192.168.1.8 \-\-trace\-stack consume\fIskb,icmp\fPrcv\fP
 .SS 诊断模式
 .PP
 使用方式与上面的一致，加个\fB\fCdiag\fR参数即可使用诊断模式。上文的生命周期模式对于使用者的

script/zh_CN/nettrace.md

@@ -98,11 +98,15 @@ nettrace - Linux系统下的网络报文跟踪、网络问题诊断工具
   进行系统丢包监控，取代原先的`droptrace`
 
 `--drop-stack`
-  打印kfree_skb内核函数的调用堆栈
+  打印kfree_skb内核函数的调用堆栈，等价于`--trace-stack kfree_skb`
 
-`--min-latency`
+`--min-latency` *latency in ms*
   根据报文的寿命进行过滤，仅打印处理时长超过该值的报文，单位为ms。该参数仅在默认和`diag`模式下可用。
 
+`--trace-stack` *traces*
+  指定需要进行堆栈打印的内核函数，可以指定多个，用“,”分隔。出于性能考虑，启用堆栈打印的
+  内核函数不能超过16个。用法和格式与`--trace`完全一致。
+
 `-v`
   显示程序启动的日志信息
 
@@ -122,6 +126,9 @@ nettrace - Linux系统下的网络报文跟踪、网络问题诊断工具
 显示详细信息：
   *nettrace -p icmp -s 192.168.1.8 --detail*
 
+打印堆栈：
+  *nettrace -p icmp -s 192.168.1.8 --trace-stack consume_skb,icmp_rcv*
+
 ### 诊断模式
 
 使用方式与上面的一致，加个`diag`参数即可使用诊断模式。上文的生命周期模式对于使用者的