Network Path Analysis with gtrace

How to Call the gtrace MCP Tools

bash
python3 $MCP_CALL "gtrace mcp" TOOL_NAME '{"param":"value"}'

When to Use

• Trace the path between two endpoints and identify each hop (router, latency, loss)
• Detect MPLS labels, ECMP load balancing, and NAT translation points along the path
• Monitor a path continuously with MTR to identify intermittent packet loss or latency spikes
• Run distributed traceroutes from 500+ GlobalPing probe locations worldwide to compare paths from different vantage points
• Verify transit providers, peering, and routing policy by inspecting AS-level path data
• Troubleshoot asymmetric routing, suboptimal paths, or blackholes

Available Tools

| Tool | Purpose | Requirements | |------|---------|-------------| | traceroute | Advanced traceroute with MPLS, ECMP, and NAT detection | cap_net_raw | | mtr | Continuous MTR monitoring with packet loss and jitter stats | cap_net_raw | | globalping | Distributed traceroute/ping from 500+ worldwide probe locations | Internet access (optional GLOBALPING_API_KEY) |

Workflow: Path Troubleshooting

When asked "why is traffic slow to X?" or "trace the path to X":

Step 1: Traceroute

Run an advanced traceroute to see every hop, latency, and any MPLS/ECMP/NAT indicators.

bash
python3 $MCP_CALL "gtrace mcp" traceroute '{"target":"8.8.8.8"}'

For IPv6:

bash
python3 $MCP_CALL "gtrace mcp" traceroute '{"target":"2001:4860:4860::8888"}'

Step 2: Continuous Monitoring with MTR

If the traceroute shows packet loss or high latency at a specific hop, run MTR to monitor continuously and confirm the problem is persistent.

bash
python3 $MCP_CALL "gtrace mcp" mtr '{"target":"8.8.8.8","count":100}'

Step 3: Global Perspective

Compare paths from multiple worldwide locations to determine if the issue is local or global.

bash
python3 $MCP_CALL "gtrace mcp" globalping '{"target":"8.8.8.8","from":"US,EU,Asia"}'

Workflow: MPLS Path Verification

Verify MPLS label-switched paths and label stacks along the path:

bash
python3 $MCP_CALL "gtrace mcp" traceroute '{"target":"10.0.0.1"}'

Look for MPLS label information in the hop details. Useful for verifying traffic engineering and MPLS VPN paths.

Workflow: ECMP Load Balancing Verification

Detect if traffic is being load-balanced across multiple equal-cost paths:

bash
python3 $MCP_CALL "gtrace mcp" traceroute '{"target":"192.168.1.1"}'

ECMP detection reveals when multiple next-hops exist at a given TTL, indicating load balancing.

Tool Parameters

traceroute

• target (required): IP address or hostname to trace

mtr

• target (required): IP address or hostname to monitor
• count (optional): Number of probe rounds to send

globalping

• target (required): IP address or hostname to probe
• from (optional): Comma-separated list of probe locations (countries, cities, regions, ASNs)

Output Format

All tools return structured results including:

• traceroute — hop number, IP, hostname, RTT per probe, MPLS labels, ECMP paths, NAT detection
• mtr — hop number, loss%, sent/recv counts, best/avg/worst/stdev RTT
• globalping — per-probe-location results with path data, useful for global path comparison

Important Rules

• Traceroute and MTR require cap_net_raw capability on the gtrace binary (set during install)
• GlobalPing uses the public GlobalPing API — set GLOBALPING_API_KEY for higher rate limits
• Always start with a single traceroute before running continuous MTR
• Use GlobalPing to differentiate local vs global path issues
• Cross-reference hop IPs with asn_lookup and geo_lookup from gtrace-ip-enrichment skill for full context
• Record all path analysis in GAIT