DEV Community

Cover image for I got tired of copying ping, traceroute, MTR and port checks so I built pingtrace
Tia Zanella
Tia Zanella

Posted on

I got tired of copying ping, traceroute, MTR and port checks so I built pingtrace

#networking #go #cli #opensource

I built https://github.com/skhell/pingtrace because network troubleshooting is rarely about one single command.

It usually starts simple, someone says the service XYZ is not reachable.

Then the real work begins.

  1. You ping the target.
  2. You run traceroute or tracert.
  3. You maybe run MTR.
  4. You check DNS.
  5. You check whether the service port is reachable.
  6. You copy outputs into notes.
  7. You repeat the same thing for another host, then another subnet, then another environment.
  8. Finally, you try to turn all of that into evidence for a ticket, incident report, handover or RCA.
  9. And for public IPs? I let you imagine.

The problem is not that ping or traceroute are hard.
The problem is the context switching.

https://github.com/skhell/pingtrace is my attempt to reduce that friction.

What pingtrace is

https://github.com/skhell/pingtrace is a terminal-first CLI for rapid network troubleshooting.

It combines several common checks into one workflow:

  • ping
  • traceroute / tracert depending on the operating system
  • MTR-style probing
  • TCP service reachability checks without nmap or root access
  • reverse DNS enrichment
  • optional ipinfo.io enrichment
  • optional PeeringDB enrichment
  • CSV export
  • JSON export
  • multiple targets
  • CIDR ranges
  • input from file

The idea is very simple

get a clean, readable and exportable view of reachability, path and service availability in one run.

It is not meant to replace the standard tools.

I still trust ping, traceroute, mtr and still use specialized tools when I need them.
https://github.com/skhell/pingtrace sits in the middle: a practical wrapper for the troubleshooting workflow I see repeat constantly.

The workflow problem

During incidents, the technical check is only half of the job, the other half is communication.
You need to explain what you tested, from where, against which target, with what result.

For example:

  • Was ICMP reachable if not blocked by firewall?
  • Did the path complete?
  • Where did the trace stop?
  • Did DNS resolve?
  • Was TCP/443 reachable?
  • Was TCP/22 reachable?
  • Was the issue isolated to one host or a range?
  • Can I attach the output to a ticket?
  • Can someone else read the result without guessing what I did?
  • Can you handoff to the night shift to follow troubleshooting?

That is where raw terminal output becomes messy, one command is fine, while twenty terminal windows during a live incident are not.

This type of workflow is very similar when you want a "before and after" that preceed and succeed a migration.

pingtrace basic examples

Run ping and trace against one target:

pingtrace 1.1.1.1
Enter fullscreen mode Exit fullscreen mode

Run MTR mode:

pingtrace 1.1.1.1 --mtr
Enter fullscreen mode Exit fullscreen mode

Run bounded MTR and export the result:

pingtrace 1.1.1.1 --mtr --cycles 10 --interval 2 --export ./reports
Enter fullscreen mode Exit fullscreen mode

Run against multiple targets:

pingtrace 1.1.1.1,8.8.8.8,example.com
Enter fullscreen mode Exit fullscreen mode

Run against a CIDR:

pingtrace 10.0.0.0/30
Enter fullscreen mode Exit fullscreen mode

Run from a file:

pingtrace --file ./targets.csv
Enter fullscreen mode Exit fullscreen mode

Export CSV and JSON evidence:

pingtrace 1.1.1.1 --export ./reports --json
Enter fullscreen mode Exit fullscreen mode

TCP service reachability without nmap and root/admin

The latest improvement adds TCP service reachability checks.

Example:

pingtrace 10.0.0.1 --ports 22,80,443
Enter fullscreen mode Exit fullscreen mode

Against a small CIDR:

pingtrace 10.0.0.0/28 --ports 22,80,443 --export ./reports
Enter fullscreen mode Exit fullscreen mode

Or all ports:

pingtrace 10.0.0.1 --ports
Enter fullscreen mode Exit fullscreen mode

This uses TCP connect behavior and that matters because it does not require root/admin privileges.

  • No raw sockets.
  • No privileged execution.
  • No special setup for the common troubleshooting case.

It also enriches known ports with IANA service names where possible.
This is not intended to replace nmap or masscan.

Those tools are excellent and much deeper, my purpose here is again different and simple.

pingtrace --ports is for fast operational reachability checks:

Can this client reach this TCP service from here?

That question appears constantly in real infrastructure work.

Enrichment with DNS ipinfo.io and PeeringDB

Troubleshooting is easier when the output gives context, an IP address alone is not always enough and https://github.com/skhell/pingtrace can enrich results with:

  • reverse DNS
  • private DNS for internal environments
  • public DNS
  • ipinfo.io data
  • PeeringDB context

This is useful when looking at public paths, carrier hops, cloud networks, content networks or peering-related information.
Private and public addresses are handled differently, because internal infrastructure should not be treated like Internet routing data.

The goal is not to make assumptions, the goal is to give the engineer more context in the same output.

Export matters

I care a lot about export quality and standardization because troubleshooting does not end in the terminal.

Sooner or later, someone asks:

Can you send me the evidence? or Can you attach the result to the incident? or Can we use this in the RCA?

https://github.com/skhell/pingtrace can export CSV and JSON reports.

Example:

pingtrace app.example.com --export ./incident-123 --json
Enter fullscreen mode Exit fullscreen mode

For a TCP reachability check:

pingtrace app.example.com --ports 80,443 --export ./incident-123
Enter fullscreen mode Exit fullscreen mode

For a small subnet:

pingtrace 10.0.12.0/28 --ports 22,80,443 --export ./incident-123
Enter fullscreen mode Exit fullscreen mode

This makes the tool useful not only for interactive troubleshooting, but also for documentation and team handover.

What pingtrace is not

I want to keep the scope honest.

https://github.com/skhell/pingtrace is not:

  • a replacement for nmap
  • a replacement for full observability
  • a packet analyzer
  • a vulnerability scanner
  • a network monitoring platform
  • a magic root cause engine

It is a focused CLI for reachability, path visibility, TCP service checks, enrichment and export, that focus matters.
Many tools become less useful when they try to become everything.

I want https://github.com/skhell/pingtrace to stay clean and practical.

Who it is for

I am building https://github.com/skhell/pingtrace for people who actually troubleshoot and plan infrastructure changes or migration:
The best use case is when you need a fast answer and a clean repeatable artifacts.

Not just:

Is it reachable?

But also:

Can I show what I tested in a clean standardized format?

Example incident flow

A simple workflow could look like this:

mkdir incident-456

pingtrace app.example.com --mtr --cycles 10 --interval 2 --export ./incident-456 --json

pingtrace app.example.com --ports 80,443 --export ./incident-456

pingtrace 10.0.12.0/28 --ports 22,80,443 --export ./incident-456
Enter fullscreen mode Exit fullscreen mode

At the end, I have a directory with evidence I can reuse and help team understanding the scope to later go deeper with Wireshark or specialized software/tools. That is the kind of boring operational detail that matters during real incidents addressing fast answers.

What comes next

The direction I want for https://github.com/skhell/pingtrace is clear:

  • better troubleshooting evidence
  • better exports with IEEE oui integration
  • cleaner output
  • standardization improvements
  • no unnecessary privileges great in enterprise environments
  • practical workflows for real infrastructure teams

I am not trying to build a flashy tool, I am trying to build something I would actually use under pressure.

Feedback wanted

If you work in networking, cloud, SRE, infrastructure support or incident response, I would really appreciate feedback.
The most useful feedback is not only "nice project", the most useful feedback is:

  • this output field is missing
  • this flag is confusing
  • this workflow does not match reality
  • this would help during RCA
  • this should stay out of scope
  • this would make it easier for a team to adopt

GitHub: https://github.com/skhell/pingtrace

If it saves time in one troubleshooting session, it was worth building.

Top comments (0)