traceroute: Trace the Network Path in CI
traceroute reveals each router (hop) a packet crosses to reach a host, and where the path stops responding.
When a host is unreachable and you need to know whether the problem is near the runner, mid-path, or at the destination, traceroute shows the hop where replies stop and the latency along the way.
What it does
traceroute sends packets with increasing TTL values; each router that decrements TTL to zero returns an ICMP Time Exceeded, revealing its address. The output is one line per hop, so a run of asterisks marks where the path stops responding.
Common usage
# numeric output, skip slow reverse-DNS
traceroute -n db.internal
# use TCP SYN to a port (passes firewalls that block UDP/ICMP probes)
traceroute -T -p 443 -n api.example.com
# cap the number of hops
traceroute -m 15 -n db.internalOptions
| Flag | What it does |
|---|---|
| -n | Numeric output, no reverse DNS (faster) |
| -T | TCP probes (Linux traceroute) instead of UDP |
| -p <port> | Destination port for the probes |
| -m <hops> | Maximum number of hops to probe |
| -w <secs> | Per-hop reply timeout |
| -I | Use ICMP echo probes |
In CI
Default UDP/ICMP probes are often blocked, producing all-asterisk output that looks like total failure even when the service works. Prefer -T -p <port> to trace using the real TCP port, which firewalls along the path are more likely to permit.
Common errors in CI
A line of "* * *" at the final hop means that router does not answer probes, not necessarily that the destination is down; trailing asterisks are normal. "traceroute: <host>: Name or service not known" is a DNS failure. "traceroute: command not found" on slim images means installing traceroute (or using tracepath, which needs no root).