annotator

Documentation

Overview

Package annotator provides structs and interfaces used throughout the program.

Index

• Variables
• type Annotations
• type Annotator
• type ClientAnnotations
• type Direction
  • func FindDirection(ID *inetdiag.SockID, localIPs []net.IP) (Direction, error)
• type Geolocation
• type Network
  • func (n *Network) FirstASN() uint32
• type ServerAnnotations
• type System

Variables

var (
	// ErrNoAnnotation is for when we could not perform an annotation for some
	// reason. It is intended to convey that the annotation system is still
	// functioning fine, but one or more of the annotations you asked for could
	// not be performed.
	ErrNoAnnotation = errors.New("Could not annotate IP address")
)

Types

type Annotations

type Annotations struct {
	UUID      string
	Timestamp time.Time
	Server    ServerAnnotations `json:",omitempty" bigquery:"server"` // Use Standard Top-Level Column names.
	Client    ClientAnnotations `json:",omitempty" bigquery:"client"` // Use Standard Top-Level Column names.
}

Annotations contains the standard columns we would like to add as annotations for every UUID.

type Annotator

type Annotator interface {
	Annotate(ID *inetdiag.SockID, annotations *Annotations) error
}

Annotator is the interface that all systems that want to add metadata should implement.

type ClientAnnotations

type ClientAnnotations struct {
	Geo     *Geolocation `json:",omitempty"` // Holds the Client geolocation data
	Network *Network     `json:",omitempty"` // Holds the Autonomous System data.
}

ClientAnnotations are client-specific fields for annotation metadata with pointers to geo location and ASN data.

type Direction

type Direction int

Direction gives us an enum to keep track of which end of the connection is the server, because we are informed of connections without regard to which end is the local server.

const (
	Unknown Direction = iota
	SrcIsServer
	DstIsServer
)

Specific directions.

func FindDirection

func FindDirection(ID *inetdiag.SockID, localIPs []net.IP) (Direction, error)

FindDirection determines whether the IPs in the given ID map to the server or client annotations. FindDirection returns the corresponding "src" and "dst" annotation fields from the given annotator.Annotations.

type Geolocation

type Geolocation struct {
	ContinentCode string `json:",omitempty"` // Gives a shorthand for the continent
	CountryCode   string `json:",omitempty"` // Gives a shorthand for the country
	CountryCode3  string `json:",omitempty"` // Geo1: Gives a shorthand for the country
	CountryName   string `json:",omitempty"` // Name of the country
	Region        string `json:",omitempty"` // Geo1: Region or State within the country

	// Subdivision fields are provided by MaxMind Geo2 format and used by uuid-annotator.
	Subdivision1ISOCode string `json:",omitempty"`
	Subdivision1Name    string `json:",omitempty"`
	Subdivision2ISOCode string `json:",omitempty"`
	Subdivision2Name    string `json:",omitempty"`

	MetroCode        int64   `json:",omitempty"` // Metro code within the country
	City             string  `json:",omitempty"` // City within the region
	AreaCode         int64   `json:",omitempty"` // Geo1: Area code, similar to metro code
	PostalCode       string  `json:",omitempty"` // Postal code, again similar to metro
	Latitude         float64 `json:",omitempty"` // Latitude
	Longitude        float64 `json:",omitempty"` // Longitude
	AccuracyRadiusKm int64   `json:",omitempty"` // Geo2: Accuracy Radius (since 2018)

	Missing bool `json:",omitempty"` // True when the Geolocation data is missing from MaxMind.
}

The Geolocation struct contains all the information needed for the geolocation MaxMind Geo1 and Geo2 data used to annotate BigQuery rows.

This is in common because it is used by the etl repository.

type Network

type Network struct {
	CIDR     string `json:",omitempty"` // The IP prefix found in the RouteViews data.
	ASNumber uint32 `json:",omitempty"` // First AS number.
	ASName   string `json:",omitempty"` // AS name for that number, data from IPinfo.io
	Missing  bool   `json:",omitempty"` // True when the ASN data is missing from RouteViews.

	// Systems may contain data for Multi-Origin ASNs. Typically, RouteViews
	// records a single ASN per netblock.
	Systems []System `json:",omitempty"`
}

Network contains the Autonomous System information associated with the IP prefix. Roughly 99% of mappings consist of a single System with a single ASN.

func (*Network) FirstASN

func (n *Network) FirstASN() uint32

FirstASN gives the ASN that should be used by systems that don't want to deal with the complication of MOAS IP addresses.

type ServerAnnotations

type ServerAnnotations struct {
	Site    string       `json:",omitempty"` // M-Lab site, i.e. lga01, yyz02, etc.
	Machine string       `json:",omitempty"` // Specific M-Lab machine at a site, i.e. "mlab1", "mlab2", etc.
	Geo     *Geolocation `json:",omitempty"` // Holds the Server geolocation data.
	Network *Network     `json:",omitempty"` // Holds the Autonomous System data.
}

ServerAnnotations are server-specific fields populated by the uuid-annotator.

type System

type System struct {
	// ASNs contains a single ASN, or AS set. There must always be at least one
	// ASN. If there are more than one ASN, they will be listed in the same order
	// as RouteViews.
	ASNs []uint32
}

A System is the base element. It may contain a single ASN or multiple ASNs comprising an AS set.