veneur: Index | Files | Directories

package protocol

import ""

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.


Package Files

addr.go errors.go wire.go


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.

func IsFramingError Uses

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 Uses

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 Uses

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 Uses

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:


func ValidTrace Uses

func ValidTrace(span *ssf.SSFSpan) bool

ValidTrace returns true if an SSFSpan contains all data necessary to synthesize a span that can be used as part of a trace.

func ValidateTrace Uses

func ValidateTrace(span *ssf.SSFSpan) error

ValidateTrace is identical to ValidTrace, except instead of returning a boolean, it returns a non-nil error if the SSFSpan cannot be interpreted as a span, and nil otherwise.

func WriteSSF Uses

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.

type InvalidTrace Uses

type InvalidTrace struct {
    // contains filtered or unexported fields

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

func (*InvalidTrace) Error Uses

func (e *InvalidTrace) Error() string



Package protocol imports 8 packages (graph) and is imported by 21 packages. Updated 2019-04-01. Refresh now. Tools for package owners.