traceroute

README

go-traceroute

A minimalistic library for running UDP route tracing both synchronously and asynchronously.

go-traceroute provides a simple way to perform UDP tracing in Go.
It aims to be simple to use with minimal configuration. IT can be used either synchronously, i.e. call a trace and wait for the final result, or asynchronously by starting a trace in a goroutine and collect the results for integration in realtime applications.

Usage

Synchronous

package main

import (
	"fmt"
	tracer "github.com/kjansson/go-traceroute"
)

func main() {

	t := tracer.New()
	t.Address = "8.8.8.8"

	// Synchronous output of hops after trace is complete

	result, err := tracer.Trace()
	if err != nil {
		panic(err)
	}

	fmt.Println("Trace completed. Hops:")

	for _, hop := range result.Hops {
		fmt.Printf("Hop: %d, %s, Host: %s, Latency: %.2f ms\n", hop.TTL, hop.Address, hop.Host, hop.Latency)
	}
}

Aynchronous

package main

import (
	"fmt"
	"os"
	"os/signal"
	"syscall"

	tracer "github.com/kjansson/go-traceroute"
)

func main() {

	t := tracer.New()
	t.Address = "8.8.8.8"

    // Collect realtime output

	cancelChan := make(chan os.Signal, 1)
	signal.Notify(cancelChan, syscall.SIGTERM, syscall.SIGINT)

	go t.Trace()
	for {
		select {
		case hop := <-tracer.ResultChan:
			fmt.Printf("Hop: %d, %s, Host: %s, Latency: %.2f ms, Reachable: %t\n", hop.TTL, hop.Address, hop.Host, hop.Latency, hop.Reachable)
			if !hop.Reachable {
				fmt.Println("Trace completed.")
				os.Exit(0)
			}
		case <-cancelChan:
			fmt.Println("Trace cancelled.")
			os.Exit(0)
		}
	}
}

Configuration

The Tracer struct returned by the constructor New can be configured prior to executing a trace. The following fields are configurable;

type Tracer struct {
	Address    string        // Trace target address
	Port       int           // Destination port
	StartTTL   int           // Starting TTL value
	MaxTTL     int           // Maximum TTL value
	Timeout    time.Duration // Timeout for each hop
	DNSLookup  bool          // Enable DNS host lookup for hop addresses
}

Trace result

The Traceresult struct contains the trace result in the form of an ordered array of hops;

type Hop struct {
	TTL       int     // Time To Live value for this hop
	Address   string  // IP address of the hop
	Host      string  // Resolved hostname of the hop
	Latency   float64 // Latency in milliseconds to reach this hop
	Reachable bool    // Whether the hop was reachable based on ICMP
}

Trace result can be read in two ways;

1. Reading theTraceResult struct returned after trace execution.
2. Reading the ResultChan channel which continously publishes completed hops during execution.

Documentation

Index

• Constants
• type Hop
• type TraceResult
• type Tracer
  • func New() *Tracer
  • func (t *Tracer) Trace() (TraceResult, error)

Constants

const UnexpectedICMPType = -1 // Represents an unexpected ICMP type

Types

type Hop

type Hop struct {
	TTL       int     // Time To Live value for this hop
	Address   string  // IP address of the hop
	Host      string  // Resolved hostname of the hop
	Latency   float64 // Latency in milliseconds to reach this hop
	Reachable bool    // Whether the hop was reachable based on ICMP
}

Type hop represents a single hop in a traceroute

type TraceResult

type TraceResult struct {
	Hops []Hop
}

TraceResult holds the hops collected during a trace

type Tracer

type Tracer struct {
	Address    string        // Trace target address
	Port       int           // Destination port
	StartTTL   int           // Starting TTL value
	MaxTTL     int           // Maximum TTL value
	Timeout    time.Duration // Timeout for each hop
	DNSLookup  bool          // Enable DNS host lookup for hop addresses
	ResultChan chan Hop      // Channel to send hop results asynchronously
}

Tracer struct holds configuration and result channel for asynchronous use

func New

func New() *Tracer

New creates a new tracer instance with default settings and initialized result channel

func (*Tracer) Trace

func (t *Tracer) Trace() (TraceResult, error)

Trace performs the traceroute operation and returns the collected hops both synchronously and via the ResultChan