shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringAPI key requirement unconfirmed

gtrace-path-analysis

Network path tracing and monitoring — traceroute with MPLS/ECMP/NAT detection, continuous MTR monitoring, and distributed GlobalPing probes from 500+ worldwide locations

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Network Path Analysis with gtrace

Installer note: native registration and the documented MCP_CALL invocation share the installed component launcher. Check readiness.json before first use; failed discovery is not device state. Existing write approvals still apply.

How to Call the gtrace MCP Tools

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.

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

For IPv6:

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.

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.

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:

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:

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

Failure Behavior

  • If a tool call fails with an authentication or connection error, check that GTRACE_MCP_BIN is set and valid before assuming a data or device problem.
  • On a tool error (timeout, unreachable host, malformed response), report the failure and its error message directly to the user rather than fabricating or guessing at results.
  • For a confirmed read-only call, check connectivity and retry once if appropriate. For any call that changes state or sends a message, a timeout does not prove the action failed: inspect current state or delivery status before retrying, preserve the required approval/change gates, and do not repeat an action whose outcome is unknown.