Modern Go rewrite inspired by paping.
paping-go is an independent Go rewrite inspired by the original paping tool by Mike Lovell.
This project is not a fork and does not include original paping source code.
It performs ping-like TCP port reachability checks and reports connection timing, making it useful when ICMP ping is blocked or when the service-level TCP path matters more than host reachability.
- TCP port reachability checks
- Ping-like repeated connection attempts
- Latency/timing output
- Count-based runs
- Duration-based runs
- Configurable interval/rate
- IPv4 / IPv6 selection
- Optional colored output
- CSV output for later analysis
- Built-in HTML report generation from CSV
- Optional standalone HTML viewer for large CSV inspection
- Cross-platform builds for Linux, Windows and macOS
Build from source:
go build -o paping-go ./cmd/paping-goInstall with Go:
go install github.com/basecubedev/paping-go/cmd/paping-go@latestOnce releases are published, most users should download prebuilt binaries from GitHub Releases.
For most Linux systems, use the normal linux-amd64 or linux-arm64 binary.
For very old Linux distributions or kernels, use linux-amd64-legacy.
All Linux release binaries are built as static pure-Go binaries and do not require a specific GLIBC version.
Tagged releases provide Debian packages for amd64 and arm64.
Download the matching .deb file from the GitHub Release page and install it with:
sudo apt install ./paping-go_0.1.1_amd64.debAfter installation, run:
paping-go --version
paping-go -p 443 -c 3 example.comTo remove it:
sudo apt remove paping-gopaping-go -p 443 example.comFlags use Go's standard flag parser. Put options before the destination host:
paping-go -p 443 -c 5 -t 1000 example.comOptions:
Usage:
paping-go [options] <host>
paping-go report <csv-file> -o <report.html> [--max-chart-points N] [--full-chart] [--output-mode 0600|0644] [--no-clobber]
Examples:
paping-go -p 443 -c 5 example.com
paping-go -p 443 -c 100 -o results.csv example.com
paping-go report results.csv -o report.html
paping-go report results.csv -o report.html --max-chart-points 50000
-p N TCP port (required)
-c N number of checks (-1 = infinite, default: -1)
-d DURATION run for duration; cannot be combined with -c
-r N requests per second (default: 1, e.g. 0.5, 2, 10)
-t N timeout in milliseconds (default: 1000)
-4 force IPv4
-6 force IPv6
-all-ips test all resolved IP addresses matching -4/-6; -r controls full IP cycles per second
-o FILE write results to CSV file
-output-mode MODE output file permissions: 0600 or 0644 (default: 0600)
-no-clobber fail if the output file already exists
-nocolor disable color output
-version print version and exit
Report options:
--max-chart-points N maximum embedded chart points; statistics still use the full CSV (default: 20000)
--full-chart embed every chart point; can create very large HTML reports for long measurements
Use either -c or -d to limit a run. -c -1 enables continuous mode, -c 0 is invalid, and -c and -d cannot be used together.
With -all-ips, the rate controls probe cycles per second. Each cycle probes every selected IP address, so -r 1 with five selected IPs can perform up to five TCP checks per second.
Check HTTPS three times:
paping-go -p 443 -c 3 example.comRun for 30 seconds at two checks per second:
paping-go -p 443 -d 30s -r 2 example.comForce IPv4:
paping-go -4 -p 443 example.comTest every resolved IPv4 address:
paping-go -4 -all-ips -p 443 -c 3 example.comIn this mode, each count is a full cycle over all selected IPs.
Write CSV output:
paping-go -p 443 -c 10 -o results.csv example.comBy default, generated CSV and HTML report files are written with private permissions (0600) because they may contain internal hostnames, IP addresses, latencies, and connection errors.
For intentionally shared outputs, choose 0644 explicitly:
paping-go -p 443 -c 10 -o results.csv --output-mode 0644 example.com
paping-go report results.csv -o report.html --output-mode 0644Use 0644 only when the file may be readable by other local users or a webserver.
Use --no-clobber to avoid overwriting existing output files:
paping-go -p 443 -c 10 -o results.csv --no-clobber example.com
paping-go report results.csv -o report.html --no-clobberGenerate an HTML report from CSV output:
paping-go report results.csv -o report.htmlCSV output contains:
timestamp,host,ip,port,status,latency_ms
Successful rows use ok for status and include latency in milliseconds. Failed rows use the failure reason in the status field and leave latency_ms empty.
The ip column records the concrete address tested. With -all-ips, each matching resolved address is tested and written as its own row.
CSV is the machine-readable raw output. The built-in HTML report is intended for visual inspection and sharing in diagnostics, support requests, and GitHub issues.
python3 -m http.server 8080
paping-go -p 8080 -c 100 -o examples/localhost-demo.csv 127.0.0.1
paping-go report examples/localhost-demo.csv -o report.htmlReport generation is built into the paping-go binary, so users do not need to download the standalone viewer separately. The generated report includes a summary, latency statistics, streaks, time range, failure details, recent raw rows, and an offline interactive SVG chart. It does not load chart libraries from a CDN.
paping-go report is optimized for long-running measurements and large CSV files. The CSV input is scanned without keeping every row in the report model.
Report statistics are calculated from the complete CSV input, while embedded chart data is limited by --max-chart-points to keep generated HTML files responsive and reasonably small. This means:
- all samples are included in the summary statistics
- success and failure rates are calculated from the full CSV
- latency min/average/median/percentile/max values are calculated from the full CSV
- failure summaries are calculated from the full CSV
- the chart uses representative points across the whole time range
- the generated HTML report stays manageable for large measurements
By default, the generated HTML report embeds at most 20,000 evenly sampled chart points for browser performance. Use --max-chart-points N to raise or lower the chart limit. This option only limits embedded chart data; it does not change report statistics.
For intentionally embedding every data point, use:
paping-go report results.csv -o report.html --full-chartUse --full-chart only when you really need every sample in the chart, because it can create very large HTML files for long measurements.
The report chart supports zoom, pan, reset, and display toggles. Use the mouse wheel to zoom, drag to pan, double-click or Reset to restore the full range. The chart can show or hide the latency line, individual data points, and failed checks. Hover over the display options for short explanations.
For large CSV files, the HTML report keeps the tables compact:
- recent raw rows are limited
- failure rows are limited to the most recent entries
- the original CSV remains the canonical full data source
The included demo data uses localhost only and does not benchmark any third-party service.
paping-go can turn CSV output into a browser-openable HTML report.
The preview was generated from a local test server on 127.0.0.1:8080.
python3 -m http.server 8080
go build -o paping-go ./cmd/paping-go
./paping-go -p 8080 -c 100 -o examples/localhost-demo.csv 127.0.0.1
./paping-go report examples/localhost-demo.csv -o /tmp/paping-go-report.htmlOpen /tmp/paping-go-report.html in a browser and save a screenshot to:
docs/assets/report-preview.png
Open tools/viewer.html in a browser and load a CSV file generated by paping-go.
paping-go report creates a self-contained HTML report. The report limits embedded chart points by default, which keeps shared HTML files smaller for long-running measurements.
For very large CSV files, advanced users can use tools/viewer.html from the repository. The standalone viewer loads a CSV file locally in the browser instead of embedding the data into a generated report.
No data is uploaded; the CSV is processed locally by the browser.
The standalone viewer provides display toggles for the latency line, data points, and failed checks. Its filter controls which CSV rows are included, while the display controls choose how those rows are drawn.
The viewer uses a locally vendored Plotly.js file from tools/vendor/plotly.min.js, so it works offline from a repository checkout. The bundled Plotly license is stored next to it in tools/vendor/plotly.min.js.LICENSE.txt.
The minimum supported Go version for building from source is Go 1.23.
Most release binaries are built with the latest stable Go toolchain. The
additional linux-amd64-legacy artifact is built with Go 1.23.x for very old
Linux distributions. All Linux release binaries are built as static pure-Go
binaries (CGO_ENABLED=0, netgo osusergo tags) so they do not depend on a
specific GLIBC version.
Run local checks:
go mod tidy
go fmt ./...
go vet ./...
go test ./...
go test -race ./...
go build -o paping-go ./cmd/paping-goUpdate the optional standalone viewer Plotly asset:
npm install
npm run vendorInject a version at build time:
VERSION=v0.1.0
go build -ldflags "-X main.version=${VERSION}" -o paping-go ./cmd/paping-goCreate clean source archives from git so generated files such as .git/,
node_modules/, coverage profiles, and local build outputs are excluded:
tools/make-source-archive.sh HEAD paping-go.tar.gz
git archive --format=tar.gz --output=paping-go.tar.gz HEAD
git archive --format=zip --output=paping-go.zip HEADThe helper also checks that the tarball does not contain .git/,
node_modules/, dist/, or coverage.out.
The original paping tool popularized TCP port checks with familiar ping-like output. paping-go preserves that general workflow as an independent Go implementation.
See NOTICE.md for attribution details.
paping-go does not collect telemetry and does not contact any service except the target host/port requested by the user.
MIT License. See LICENSE.