Skip to content

README.md

Latest commit

 

History

History
105 lines (73 loc) · 5.16 KB

README.md

File metadata and controls

105 lines (73 loc) · 5.16 KB

pingtrace

GitHub license Go Reference Go Report Card

Pingtrace demo

Get a clean, color-coded view of every reply and every hop in a single run enriched with private and public DNS, ipinfo.io and PeeringDB policies. Easily export the results in CSV and JSON format.

Why pingtrace over the standard tools?

You usually run pingtrace gives you in one command
ping then traceroute / tracert depending on OS then mtr you run universally pingtrace that style the output and offer additional flags like MTR
dig +short for every hop reverse DNS resolved automatically, with optional private DNS for internal hops
for ip in $(seq …) loops simply pingtrace 10.0.0.0/24 or --file targets.csv
copy/paste into a spreadsheet or note --export ./reports writes timestamped UTC CSVs and pingtrace 10.0.0.0/21 do it by default; add --json for a schema-validated JSON report alongside

It's the same probes you already trust (the OS ping / traceroute) pingtrace just runs them with no additional latency overhead, parallelize requests for faster CIDR resolution, decorates outputs for clear cross-platform readability including export.

Install

macOS

brew tap skhell/pingtrace
brew install pingtrace

Linux

Download the .deb or .rpm from the latest GitHub Release and install it:

# Debian / Ubuntu
sudo dpkg -i pingtrace_linux_amd64.deb

# Fedora / RHEL
sudo rpm -i pingtrace_linux_amd64.rpm

Any platform (Go toolchain required)

go install github.com/skhell/pingtrace/cmd/pingtrace@latest

Quick start

# the headline command ping + trace + enrichment
pingtrace 1.1.1.1

# live MTR (Ctrl+C / q to stop)
pingtrace 1.1.1.1 --mtr

# bounded MTR, 10 cycles, 2s apart, exported to CSV
pingtrace 1.1.1.1 -m --cycles 10 --interval 2 --export ./reports

# CSV + JSON report (JSON validates against schema/pingtrace.schema.json)
pingtrace 1.1.1.1 --export ./reports --json

# CSV with no empty columns (e.g. skips PeeringDB columns when not configured or get empty results)
pingtrace 1.1.1.1 --export ./reports --compact-export
pingtrace 1.1.1.1 --export --json ./reports --compact-export

# multiple targets, a CIDR, or a file
pingtrace 1.1.1.1,1.1.1.1,example.com
pingtrace 10.0.0.0/30
pingtrace --file ./targets.csv

# script-friendly: pick your columns
pingtrace 1.1.1.1 --no-trace --columns seq,ip,time_ms,status

Run pingtrace --help for the grouped, color-coded flag reference, and pingtrace config to open an interactive TUI for tokens, DNS, and thresholds.

Operational notes

  • pingtrace depends on system ping and traceroute tooling being available on PATH.
  • On Windows, tracert is used.
  • On Unix-like systems, traceroute is used, with tracepath as a fallback where available.
  • --export without a path writes operation-specific CSV files in the current working directory.
  • If --export points to a .csv file path, pingtrace uses that file's directory and still writes separate ping_...csv and trace_...csv files.
  • CSV rows include a source column (local outbound IP of the machine running pingtrace) and a target column (the hostname or IP passed on the command line). Both appear on every row so exports from multiple machines can be merged and filtered without ambiguity.
  • --compact-export omits columns that are entirely empty across all rows (e.g. PeeringDB columns when PeeringDB is not configured, ipinfo columns when no token is set). The column set is locked on the first write and stays consistent for the whole file.
  • Private DNS enrichment is automatically skipped if the configured server does not respond within 5 seconds.
  • --json writes a sibling JSON report (probe_...json for ping/trace runs, mtr_<target>_...json per MTR target) into the same directory as --export, or the current working directory when --export is omitted. The document validates against schema/pingtrace.schema.json and lists any CSVs written in its exportedFiles section.
  • PeeringDB and ipinfo.io enrichment is skipped for private/RFC-1918 IP addresses.

Feedback

If pingtrace saved you time in a troubleshooting session, it was worth building.

  • Star the project on GitHub
  • Report bugs or request features in Issues
  • Buy me a coffee, or a snack for my buddy Schnauzer Tyson GitHub if you feel this project was useful to your or your team.