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.
- 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
MaxSSFPacketLength is the maximum length of an SSF packet. This is currently 16MB.
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.
This section is empty.
func IsFramingError ¶
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.
ParseSSF takes in a byte slice and returns: a normalized SSFSpan and an error if any errors in parsing the SSF packet occur.
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 ¶
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 ¶ added in v1.8.0
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 ¶
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.
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.