The highest tagged major version is
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
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.
Variables ¶
This section is empty.
Functions ¶
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.
func ParseSSF ¶ added in v1.8.0
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 ¶
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 returns true if an SSFSpan contains all data necessary to synthesize a span that can be used as part of a trace.
func ValidateTrace ¶ added in v1.9.0
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.
Types ¶
type InvalidTrace ¶ added in v1.8.0
type InvalidTrace struct {
// contains filtered or unexported fields
}
InvalidTrace is an error type indicating that an SSF span was invalid.
func (*InvalidTrace) Error ¶ added in v1.8.0
func (e *InvalidTrace) Error() string
Source Files
Directories