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 ResolveAddr(str string) (net.Addr, error)
• func ValidTrace(sample *ssf.SSFSpan) bool
• func WriteSSF(out io.Writer, ssf *ssf.SSFSpan) (int, error)
• type InvalidTrace
  • func (e *InvalidTrace) Error() string
• type Message
  • func ParseSSF(packet []byte) (*Message, error)
  • func ReadSSF(in io.Reader) (*Message, error)
  • func (m *Message) Metrics() []*ssf.SSFSample
  • func (m *Message) TraceSpan() (*ssf.SSFSpan, error)

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 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(sample *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 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

type Message

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

A Message struct represents a parsed SSF message. It encapsulates an ssf.SSFSpan object, which can contain a trace span and/or a set of metrics.

func ParseSSF

func ParseSSF(packet []byte) (*Message, 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) (*Message, 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 (*Message) Metrics

func (m *Message) Metrics() []*ssf.SSFSample

Metrics returns the ssf samples contained in an SSF span. It does not perform any parsing or conversion.

func (*Message) TraceSpan

func (m *Message) TraceSpan() (*ssf.SSFSpan, error)

TraceSpan checks if an SSF message is a valid trace. If so, it returns a pointer to that original span. If the span is not a valid trace, TraceSpan returns nil and an *InvalidTrace error type.

The span returned from TraceSpan does contain the (unparsed) metric samples contained in the span. Note also that since the data returned is a pointer to the original span, it's not advisable to modify that span directly.