A powerful cross-platform application for monitoring, analyzing, and accessing PTPv2 (Precision Time Protocol) networks in real-time with multiple operation modes: Interactive TUI or Headless Monitoring.
PTP Trace offers two flexible modes of operation:
- 🖥️ Interactive TUI - Full-featured terminal UI with mouse support for interactive monitoring
- 📊 Headless Mode - Background monitoring with event logging
All modes share a common service layer and support both live packet capture and offline PCAP analysis.
- Real-time dashboard with multiple panels
- Multiple themes: Default, Monokai, Matrix
- Intuitive keyboard navigation
- Mouse support - Click to switch views, select rows, and navigate content
- Responsive layout that adapts to terminal size
- Live updates without screen flicker
- Pause mode to temporarily stop network parsing for UI inspection
- Background monitoring without TUI overhead
- Comprehensive event logging:
- Grandmaster changes (BMCA election results)
- PTP domain changes
- Clock quality degradation
- Host timeouts and state changes
- Time transmitter selection changes
- Network interface link state changes
- IP address changes
- Host discoveries and updates
- Human-readable logging with timestamps
- Configurable log levels (error, warn, info, debug)
- Runs as a daemon-friendly service
- Automatic PTP and gPTP host discovery (UDP ports 319/320 and Ethernet 0x88f7)
- Cross-platform packet capture - Uses pnet for live capturing on Linux, macOS, and Windows
- Dual protocol support - Handles both PTP over UDP (Layer 3) and gPTP over Ethernet (Layer 2, IEEE 802.1AS)
- PCAP file support - Read and analyze PTP packets from captured pcap files (offline analysis mode)
- Multicast group membership - Ensures network interfaces receive multicast PTP traffic
- Full packet analysis - Records both raw packet data and parsed PTP content
- Smart interface selection - Automatically filters virtual interfaces while supporting manual override
- Host classification by PTP state
- BMCA (Best Master Clock Algorithm) - Automatic time transmitter detection
- Grandmaster marked with "GM" indicator
- Network statistics and quality metrics
- Timing relationship tracking
- Time reference modes - Live network uses current system time; pcap mode uses last packet timestamp as reference
- Tree view mode (TUI only) - Hierarchical display showing transmitter-receiver relationships
- Visual hierarchy mapping of transmitter-receiver relationships
- VLAN support - Detects and displays VLAN tags in PTP packets
- Native VLAN - Supports specifying native vlan id on interfaces
- Comprehensive host table with sortable columns
- Multiple sort options (State, IP, Clock Identity, Domain, etc.)
- Selection tracking across operations
- Quality indicators and confidence levels
- OUI database integration to show vendor information
- Local machine identification: Your own machine is marked with asterisks (*)
- Mouse-enabled selection - Click on any host row to select it instantly
- Real-time packet history with version identification
- Color-coded message types (ANNOUNCE, SYNC, DELAY_REQ, PDELAY_REQ, etc.)
- Interface-aware capture - Tracks which interface each packet was received on
- Interactive packet selection - Click to select packets, double-click for detailed view
- Scroll wheel support - Navigate through packet history with mouse wheel
- Rust 1.70.0 or later
- Administrator privileges required - Needed for promiscuous mode packet capture (in live capture mode)
- Network interfaces with PTP traffic (ports 319/320)
- Platform-specific requirements:
- macOS: Xcode command line tools (
xcode-select --install) - Windows: WinPcap or Npcap installed
- macOS: Xcode command line tools (
# Clone the repository
git clone https://github.com/holoplot/ptp-trace.git
cd ptp-trace
# Build from source
cargo build --release
# Run with default settings (TUI mode, requires root)
sudo ./target/release/ptp-trace# Monitor with default TUI (requires root)
sudo ./target/release/ptp-trace
# Monitor specific interface
sudo ./target/release/ptp-trace --interface eth0
# Monitor multiple interfaces
sudo ./target/release/ptp-trace --interface eth0 --interface eth1
# Use Matrix theme with faster updates
sudo ./target/release/ptp-trace --theme matrix --update-interval 500
# Disable mouse support
sudo ./target/release/ptp-trace --no-mouse
# Analyze PCAP file (no admin privileges needed)
./target/release/ptp-trace --pcap-file capture.pcap# Monitor in headless mode with all events logged (default: info level)
sudo ./target/release/ptp-trace --headless
# Log only critical events (error level) - GM changes, timeouts, link down, quality degradation
sudo ./target/release/ptp-trace --headless --log-level error
# Log critical and state change events (warn level) - error + host updates
sudo ./target/release/ptp-trace --headless --log-level warn
# Verbose logging including all packets (debug level)
sudo ./target/release/ptp-trace --headless --log-level debug
# Monitor specific interface with custom web port
sudo ./target/release/ptp-trace -i eth0 --headless --web-port 9090
# Example output (one line per event):
# [2026-02-09 10:23:45.123] INFO: New host discovered | id=00:11:22:33:44:55:66:77 domain=0 ips=[192.168.1.100(eth0)] interfaces=[eth0]
# [2026-02-09 10:24:12.456] ERROR: Grandmaster changed in domain 0 | old=00:11:22:33:44:55:66:77 new=aa:bb:cc:dd:ee:ff:00:11Usage: ptp-trace [OPTIONS] [COMMAND]
Options:
-i, --interface <INTERFACE> Network interface(s) to monitor
-f, --pcap-file <FILE> Read from PCAP file (offline analysis)
-u, --update-interval <MS> Update interval in milliseconds [default: 1000]
-d, --debug Enable debug logging
-t, --theme <THEME> Color theme (default, monokai, matrix) [default: default]
--no-mouse Disable mouse support (TUI mode)
--headless Run in headless mode (no TUI)
--log-level <LEVEL> Log level: error, warn, info, debug [default: info]
-h, --help Print help
-V, --version Print versionTab- Cycle between views: Host Table → Host Details → Packet History↑/k- Move selection up or scroll up↓/j- Move selection down or scroll downPgUp/PgDn- Page navigation (10 items)Home/End- Jump to top/bottomEnter- Show packet details modalq- Close modal/help or quit applicationEsc- Close help screen
Click- Switch to view and select rowDouble-click- Open packet details modalClick outside modal- Close modalScroll wheel- Navigate selections/scroll content
s- Cycle sort columnsS- Toggle sort directiona- Previous sort columnt- Toggle tree view mode
r- Refresh/rescan networkCtrl+L- Refresh/redraw screenc- Clear hosts and packet historyx- Clear packet history for selected hostp- Toggle pause modew- Toggle packet auto-scrolle- Toggle expanded packet historyd- Toggle debug mode
h/F1- Show/hide helpq- Quit application
PTP Trace supports offline analysis of PTP traffic from pcap files.
# Capture PTP traffic with tcpdump (Linux/macOS)
sudo tcpdump -i eth0 -w ptp_capture.pcap 'udp port 319 or udp port 320 or ether proto 0x88f7'
# Capture with Wireshark (all platforms)
# Filter: udp.port == 319 or udp.port == 320 or eth.type == 0x88f7
# Save as: ptp_capture.pcap
# Analyze in TUI mode
./target/release/ptp-trace --pcap-file ptp_capture.pcap
# Analyze in headless mode
./target/release/ptp-trace --pcap-file ptp_capture.pcap --headlessNote: PCAP analysis does not support native VLAN specification at this time.
In accordance with IEEE 1588g-2022, this project uses inclusive terminology to describe the roles of network components.
| Inclusive term | Industry Standard | Description |
|---|---|---|
| Time Transmitter | Master Clock | Device that provides timing reference |
| Time Receiver | Slave Clock | Device that synchronizes to timing reference |
The term Grandmaster remains unchanged and refers to the clock at the top of the hierarchy.
A blog post from Meinberg has more information about the topic.
Choose from multiple built-in themes for TUI mode:
- default - Clean and professional
- monokai - Dark theme with vibrant colors
- matrix - Green-on-black terminal aesthetic
Use --theme <name> to select a theme.
- ✅ Complete terminal UI framework with keyboard and mouse support
- ✅ Headless monitoring mode with event logging
- ✅ Full raw packet payloads for hexdump display
- ✅ Cross-platform packet capture (Linux, macOS, Windows)
- ✅ PCAP file analysis (offline mode)
- ✅ Host table with sorting and scrolling
- ✅ Packet history with detailed view
- ✅ Multiple theme support
- ✅ Real-time event streaming
- ✅ Network interface monitoring
- ✅ Comprehensive keyboard controls
- ✅ Debug mode with scroll information
# Development build
cargo build
# Optimized release build
cargo build --release
# Run tests
cargo test
# Format code
cargo fmt
# Lint code
cargo clippyThis project features an integrated OUI database for MAC address lookup. The information is compiled into the binary at build time.
# Update OUI database
python3 -r oui/requirements.txt
python3 oui/gen_oui_rust_phf.py >src/oui_map.rs
# Lint after updating
cargo clippyCore:
- ratatui - Terminal UI framework
- tokio - Async runtime
- crossterm - Cross-platform terminal handling
- clap - Command line argument parsing
- anyhow - Error handling
Networking:
- pnet - Cross-platform packet capture
- socket2 - Advanced socket operations and multicast
- libc - Low-level system calls
Utilities:
- chrono - Date and time
- if-addrs - Network interface enumeration
- phf - Compile-time hash tables
- serde - Serialization
We welcome contributions! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Update documentation
- Submit a pull request
- Follow Rust best practices
- Document public APIs
- Include tests for new features
- Use
cargo fmtfor formatting - Pass
cargo clippylints
This project is licensed under the GPLv2 License - see the LICENSE file for details.