User Guide

This guide explains how to use PyMTR during real troubleshooting sessions. PyMTR is designed for analysts who need a stable route view, live packet-loss and latency metrics, and exportable evidence that can be shared with network, systems, carrier, or application teams.

1. Start a Trace

Open PyMTR.exe from the self-contained release folder for the desktop GUI, or run python -m pymtr from the project virtual environment during development.
Type a hostname or IP address in Host.
Press Enter or click Start.
Leave the trace running long enough to gather a useful sample size.
Click Stop when you want to freeze the current table for analysis or export.

The trace runs continuously until you stop it. The window title includes the active target while a trace is running, which helps when multiple PyMTR windows are open.

2. Choose Safe Options

Open Options to configure runtime behavior.

Interval (ms) controls how often probe cycles are sent. The unit is milliseconds.
Ping size (bytes) controls probe payload size.
Max. hosts in LRU list controls how many previous hosts are kept in the Host dropdown.
Resolve names enables reverse DNS while keeping IP addresses visible.
Route mode controls how the visible route behaves.
Visible columns controls which metrics are shown in the main table and exported by TXT, CSV, and HTML table exports.
Enable detailed debug telemetry should stay off unless you are debugging PyMTR itself or collecting very detailed evidence, because logs can grow quickly.

Use the default Static route mode for most incident calls. It freezes the first complete route identity so everyone can discuss stable hop numbers while counters and metrics continue to update. Use Dynamic route only when the goal is to observe route changes.

3. Read the Main Table

Each row represents a hop in the path toward the target. Hostname shows the IP and resolved name when available. Nr is the hop number.

Packet metrics:

Sent is the number of probes sent to that hop.
Recv is the number of replies received from that hop.
Drop is the number of completed probes without replies.
Loss % is the percentage of completed probes without replies.

Latency metrics are in milliseconds:

Last is the newest round-trip time.
Best is the lowest round-trip time observed.
Avg is the arithmetic average.
Worst is the highest round-trip time observed.
StDev shows latency variation around the average.
Gmean is a geometric mean that reduces the influence of extreme spikes.
LP50, LP95, and LP99 are historical latency percentiles derived from the session history.

Jitter metrics are also in milliseconds:

Jttr is the current difference between the newest and previous latency.
Javg is the average jitter.
Jmax is the largest observed jitter.
Jint is a smoothed interarrival jitter estimate.
JP50, JP95, and JP99 are historical jitter percentiles derived from the session history.

Interpret intermediate-hop loss carefully. A router can deprioritize diagnostic replies to itself while still forwarding user traffic normally. Loss that continues into later hops or the final destination is usually more important than isolated loss at one intermediate hop.

4. Reorder, Resize, and Filter Columns

Drag a column header to change the column order. PyMTR shows a vertical insertion line while dragging so you can see where the column will land.

Drag the right edge of a header to resize a column. Widths are saved in PyMTR.ini.

Use Options > Visible columns to choose which metrics appear in the main table. TXT, CSV, HTML, and clipboard table exports use the same visible column set and order.

5. Configure Thresholds by Column

Conditional formatting is configured per numeric column and applied per cell.

Right-click the header of a numeric column such as Loss %, Avg, Worst, Javg, LP95, or JP99.
Enter the Normal limit. Values at or below this threshold use the normal color.
Enter the Medium impact limit. Values above the normal limit and at or below this threshold use the warning color.
Choose the normal, warning, and critical text colors.
Click OK to save the rule.

Only cells in that column are evaluated against the rule. The rule does not change the metric calculation, the exported values, or other columns. When a rule exists for a column, cells in that column are rendered in bold only when their value triggers one of the configured colors.

To remove a rule, right-click the same numeric column and use Clear. Use thresholds as operational hints, not final diagnosis. For example, a Worst spike may be harmless if it happens once, while a sustained LP95 or Javg increase is stronger evidence of recurring instability.

6. Use Hop Details

Double-click a hop row to open Hop details. Multiple Hop Details windows can stay open at the same time.

The window is split into:

Hop identity: name, IPv4, IPv6 when available, and hop number.
Snapshot metrics: values captured when the window opened.
Live metrics: the latest values for the same hop while the trace continues.
Graph metrics: selectable historical metrics for that hop.
Chart: a line chart over real local timestamps from your computer clock.

The chart supports zoom, pan, horizontal scrolling, tooltips, resize, and Live. Live follows new samples while preserving your current zoom width. Use Reset zoom only when you intentionally want to return to the full visible range.

Use group buttons in Graph metrics to select or clear packet/percentage metrics, latency metrics, or jitter metrics. If all metrics are cleared, the chart intentionally shows no data until you choose at least one metric again.

7. Export Evidence

Use the File menu for exports.

Copy Text to clipboard copies a text snapshot of the visible table.
Copy HTML to clipboard copies an HTML snapshot of the visible table.
Export TEXT, Export CSV, and Export HTML save the visible table columns in the current order.
Generate FullReport creates one PDF for the current trace session with all catalog metrics and historical charts for every visible hop.

Use Export Chart inside Hop Details when you need evidence for one hop only. It can export PNG, JPG, HTML, or PDF.

8. Logs, Temp Data, and Crash Cleanup

File > Open Log Folder opens the telemetry log folder. Detailed logs are written only when debug telemetry is enabled in Options.

File > Open Temp Folder opens runtime data, including temporary history databases under data/history. PyMTR deletes only the history files owned by the current process/session. This avoids one PyMTR instance deleting another active instance’s data. If the app is killed abruptly, old history files may remain there for manual cleanup.

9. Downloads and Documentation

Use the Sphinx documentation site for the latest user guide, architecture, API reference, release notes, manual, and download links. The Downloads page points to GitHub Releases, older versions, checksums, and the self-contained Windows ZIP files.

The Windows release folder contains two entry points:

PyMTR.exe opens the desktop GUI.
PyMTR-CLI.exe runs command-line reports and the live terminal UI.

When running from source or an installed Python package, the console command remains pymtr.

10. Report an Issue

Use About > Report an Issue when you need to report a PyMTR problem. Before opening a new issue, search the documentation, existing GitHub Issues, and Discussions.

Good bug reports include the PyMTR version, operating system, whether you used PyMTR.exe, PyMTR-CLI.exe, or python -m pymtr, route mode, interval, timeout, target host or a sanitized equivalent, screenshots, exports, and debug telemetry when it is safe to share. PyMTR is provided without warranty, and a reported issue is not a guarantee that a fix will be possible or immediate.

11. Operational Checklist

Let the trace run long enough before concluding loss or jitter.
Prefer destination loss over isolated intermediate-hop loss.
Compare Avg, Worst, StDev, Javg, and percentiles before escalating.
Keep Static route enabled when several analysts are discussing hop numbers.
Use FullReport when handing evidence to another team.
Enable debug telemetry only when necessary.