protocol

Documentation

Overview

Package protocol contains routines for implementing veneur's SSF wire protocol to read and write framed SSF samples on a streaming network link or other non-seekable medium.

SSF Wire Protocol

SSF uses protobufs internally, which aren't encapsulated or framed in any way that would allow them to be read on a streaming network connection. To counteract that, the SSF Wire Protocol frames SSF messages in the following way:

[ 8 bits - version and type of message]
[32 bits - length of framed message in octets]
[<length> - SSF message]

The version and type of message can currently only be set to the value 0, which means that what follows is a protobuf-encoded ssf.SSFSpan.

The length of the framed message is a number of octets (8-bit bytes) in network byte order (big-endian), specifying the number of octets taken up by the SSF message that follows directly on the stream. To avoid DoS'ing Veneur instances, no lengths greater than MaxSSFPacketLength (currently 16MB) can be read or encoded.

Since this protocol does not contain any re-syncing hints, any framing error on the stream is automatically fatal. The stream must be considered unreadable from that point on and should be closed.

Index

• Constants
• func IsFramingError(err error) bool
• func ParseSSF(packet []byte) (*ssf.SSFSpan, error)
• func ReadSSF(in io.Reader) (*ssf.SSFSpan, error)
• func ResolveAddr(str string) (net.Addr, error)
• func ValidTrace(span *ssf.SSFSpan) bool
• func ValidateTrace(span *ssf.SSFSpan) error
• func WriteSSF(out io.Writer, ssf *ssf.SSFSpan) (int, error)
• type InvalidTrace
  • func (e *InvalidTrace) Error() string

Constants

const MaxSSFPacketLength uint32 = 16 * 1024 * 1024

MaxSSFPacketLength is the maximum length of an SSF packet. This is currently 16MB.

const SSFFrameLength uint32 = 1 + 4

SSFFrameLength is the length of an SSF Frame. This is currently 5 bytes - 1 byte for the version and 4 bytes for the 32-bit content length.

Functions

func IsFramingError

func IsFramingError(err error) bool

IsFramingError returns true if an error is a wire protocol framing error. This indicates that the stream can no longer be used for reading SSF data and should be closed.

func ParseSSF

func ParseSSF(packet []byte) (*ssf.SSFSpan, error)

ParseSSF takes in a byte slice and returns: a normalized SSFSpan and an error if any errors in parsing the SSF packet occur.

func ReadSSF

func ReadSSF(in io.Reader) (*ssf.SSFSpan, error)

ReadSSF reads a framed SSF span from a stream and returns a parsed SSFSpan structure and a set of statsd metrics.

If this function returns an error, client code must check it with IsFramingError to decide if the error means the stream is unrecoverably broken. The error is EOF only if no bytes were read at the start of a message (e.g. if a connection was closed after the last message).

func ResolveAddr

func ResolveAddr(str string) (net.Addr, error)

ResolveAddr takes a URL-style listen address specification, resolves it and returns a net.Addr that corresponds to the string. If any error (in URL decoding, destructuring or resolving) occurs, ResolveAddr returns the respective error.

Valid address examples are:

udp6://127.0.0.1:8000
unix:///tmp/foo.sock
tcp://127.0.0.1:9002

func ValidTrace

func ValidTrace(span *ssf.SSFSpan) bool

ValidTrace takes in an SSF span and determines if it is valid or not. It also makes sure the Tags is non-nil, since we use it later.

func ValidateTrace

func ValidateTrace(span *ssf.SSFSpan) error

ValidateTrace takes in an SSF span and determines if it is valid or not. It also makes sure the Tags is non-nil, since we use it later. If the span is not valid, it returns an error.

func WriteSSF

func WriteSSF(out io.Writer, ssf *ssf.SSFSpan) (int, error)

WriteSSF writes an SSF span with a preceding v0 frame onto a stream and returns the number of bytes written, as well as an error.

If the error matches IsFramingError, the stream must be considered poisoned and should not be re-used.

Types

type InvalidTrace

type InvalidTrace struct {
	// contains filtered or unexported fields
}

InvalidTrace is an error type indicating that an SSF span was invalid.

func (*InvalidTrace) Error

func (e *InvalidTrace) Error() string