tracer

Documentation

Overview

Package tracer takes care of all interaction with traceroute systems.

Index

• func GetMetaline(conn connection.Connection, isCache bool, cachedUUID string) string
• type Metadata
• type Paris
  • func (p *Paris) DontTrace(conn connection.Connection, err error)
  • func (p *Paris) Trace(conn connection.Connection, t time.Time) (string, error)
  • func (p *Paris) TraceFromCachedTrace(conn connection.Connection, t time.Time, cachedTest string) error
• type Scamper
  • func (*Scamper) DontTrace(conn connection.Connection, err error)
  • func (s *Scamper) Trace(conn connection.Connection, t time.Time) (out string, err error)
  • func (s *Scamper) TraceFromCachedTrace(conn connection.Connection, t time.Time, cachedTest string) error
• type ScamperDaemon
  • func (d *ScamperDaemon) MustStart(ctx context.Context)
  • func (d *ScamperDaemon) Trace(conn connection.Connection, t time.Time) (out string, err error)
  • func (d *ScamperDaemon) TraceAll(connections []connection.Connection)

Functions

func GetMetaline

func GetMetaline(conn connection.Connection, isCache bool, cachedUUID string) string

GetMetaline returns the what the first line of the output jsonl file should be. Parameter isCache indicates whether this meta line is for an original trace test or a cached test, and parameter cachedUUID is the original test if isCache is 1.

Types

type Metadata

type Metadata struct {
	UUID                    string
	TracerouteCallerVersion string
	CachedResult            bool
	CachedUUID              string
}

Metadata is the first line of the traceroute .jsonl file.

TODO: move this struct to ETL parser.

type Paris

type Paris struct {
	Binary, OutputPath string
	Timeout            time.Duration
}

Paris implements the ipcache.Tracer interface using paris-traceroute.

func (*Paris) DontTrace

func (p *Paris) DontTrace(conn connection.Connection, err error)

DontTrace skips tracing entirely. It is used strictly to inform a particular tracer about how many traces it is missing out on due to its internal problems.

func (*Paris) Trace

func (p *Paris) Trace(conn connection.Connection, t time.Time) (string, error)

Trace runs a traceroute to the remote host and port from the loal source port using paris-traceroute.

func (*Paris) TraceFromCachedTrace

func (p *Paris) TraceFromCachedTrace(conn connection.Connection, t time.Time, cachedTest string) error

TraceFromCachedTrace creates a file from a previously-existing traceroute result, rather than rerunning the current test.

type Scamper

type Scamper struct {
	Binary, OutputPath string
	ScamperTimeout     time.Duration
}

Scamper uses scamper in non-daemon mode to perform traceroutes. This is much less efficient, but when scamper crashes, it has a much lower "blast radius".

func (*Scamper) DontTrace

func (*Scamper) DontTrace(conn connection.Connection, err error)

DontTrace does not perform a trace that would have been performed, had the previous round not already returned an error. This should increment a counter that tracks the number of tests which have been "transitively failed".

func (*Scamper) Trace

func (s *Scamper) Trace(conn connection.Connection, t time.Time) (out string, err error)

Trace starts a new scamper process running the paris-traceroute algorithm to every node. This uses more resources per-traceroute, but segfaults in the called binaries have a much smaller "blast radius".

func (*Scamper) TraceFromCachedTrace

func (s *Scamper) TraceFromCachedTrace(conn connection.Connection, t time.Time, cachedTest string) error

TraceFromCachedTrace creates a file containing traceroute results that came from a cache result, rather than performing the traceroute with scamper. Because scamper-in-standalone and scamper-as-daemon use the same output format, this function is the same code for both.

type ScamperDaemon

type ScamperDaemon struct {
	*Scamper
	AttachBinary, Warts2JSONBinary, ControlSocket string
}

ScamperDaemon contains a single instance of a scamper process. Once the ScamperDaemon has been started, you can call Trace and then all traces will be centrally run and managed.

This approach has the advantage that all traces are centrally managed, which helps prevent problems with overlapping traces. It has the disadvantage that all traces are centrally managed, so if the central daemon goes wrong for some reason, there is a much larger blast radius.

func (*ScamperDaemon) MustStart

func (d *ScamperDaemon) MustStart(ctx context.Context)

MustStart starts a scamper binary running and listening to the given context. There should only be a single instance of scamper being run by traceroute-caller, and if it can't start, then traceroutes can not be performed.

We expect this function to be mostly used as a goroutine:

go d.MustStart(ctx)

func (*ScamperDaemon) Trace

func (d *ScamperDaemon) Trace(conn connection.Connection, t time.Time) (out string, err error)

Trace starts a sc_attach connecting to the scamper process for each connection.

All checks inside of this function and its subfunctions should call PanicOnError instead of Must because each trace is independent of the others, so we should prevent a single failed trace from crashing everything.

func (*ScamperDaemon) TraceAll

func (d *ScamperDaemon) TraceAll(connections []connection.Connection)

TraceAll runs N independent traces on N passed-in connections.