Traceroute 插件配置说明

一、概述

traceroute 是一款经典的路由追踪插件，通过逐跳递增 TTL 发送探测包，记录每一跳的响应节点与时延。支持 ICMP、TCP、UDP 三种协议模式，在 TCP / UDP 模式下配合底层抓包以精确关联返回的 ICMP 超时 / 不可达消息。

配置字符串为 key=value 格式，每对之间用 \r\n 分隔。

参数名	类型	是否必填	默认值	说明与影响
`host`	string	是	—	目标主机名或 IP 地址。域名会先经过 DNS 解析，解析耗时单独输出。
`port`	integer	否	`0`	目标端口。若值大于 `0` 且小于 `65536`，强制启用 TCP 模式。在 TCP / UDP 模式下若未指定端口，则默认使用 `80`。决定探测包的传输层目标端口，也影响协议自动推断逻辑。
`protocol`	string	否	自动推断	显式协议选择：`icmp`、`tcp`、`udp`。若未指定且 `port>0`，则自动使用 TCP。直接决定底层套接字类型和发送的探测包格式。

参数名	类型	是否必填	默认值	说明与影响
`hops`	integer	否	`30`	最大跳数（TTL 上限）。探测从 TTL=1 开始逐跳递增，达到此值后停止。值越大，可探测的路径越长，但耗时线性增加。
`count`	integer	否	`3`	每一跳发送的探测包数量。值越大，单跳时延统计越稳定（可消除偶然抖动），但会显著增加总耗时。
`size`	integer	否	`32`	探测包 payload 期望大小，单位字节。若未配置 `data`，插件使用默认文本并自动重复 / 截断到该长度；若配置了 `data`，则 `size` 被实际 payload 长度覆盖。ICMP 模式下为 Echo Request 数据段长度；TCP / UDP 模式下为附加数据长度。
`data`	string	否	`Ping data from networkbench.com.`	自定义探测包 payload 内容。支持 `hex:` 前缀，后续内容按十六进制解码后填入。若配置了此参数，探测包长度以 `data` 实际解码后的长度为准，`size` 参数失效。可用于构造特定 payload 以测试路径上的 DPI 或 QoS 行为。

参数名	类型	是否必填	默认值	说明与影响
`ipVersion`	string	否	IPv4	指定 IP 协议版本。填写 `ipv6` 则强制使用 IPv6 进行探测；否则默认使用 IPv4。影响域名解析的地址族、套接字创建及数据包封装格式。名字必须是 `ipVersion`
`dnsServer`	string	否	系统默认	自定义 DNS 服务器地址。填写后，`host` 的解析将强制使用该服务器，解析耗时作为独立指标输出。
`nounreached`	string	否	`0`	目标不可达错误抑制开关。填 `1` 时，即使目标在 `hops` 跳内未到达，也不会上报 `99002` 错误码，仅输出已探测路径数据。适用于只关心部分路径质量的场景。

stage	指标名	单位	说明
`0`	总耗时	ms	从任务启动到完全结束的整体耗时。反映本次 traceroute 的总执行时长。
`1`	DNS 解析时间	ms	将 `host` 解析为 IP 地址的耗时。若直接填写 IP，则该值接近 0。
`2`	到达跳数	跳	实际到达目标时的 TTL 值。若目标未到达（且 `nounreached=1`），可能为 `0` 或不输出。

错误代码	info 值	含义
`612007`	DNS 解析失败	域名解析失败
`699001`	配置错误	通常为 `host` 为空或未指定。
`699002`	目标不可达	在 `hops` 跳内未收到目标响应，且 `nounreached ≠ 1` 时上报。

host=www.example.com
hops=20
count=3
size=64

host=www.example.com
port=443
protocol=tcp
hops=30
count=5

host=8.8.8.8
port=53
protocol=udp
hops=25
size=1024

host=2001:4860:4860::8888
ipVersion=ipv6
protocol=icmp
hops=30