ssf

package
v2.0.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 9, 2018 License: MIT Imports: 6 Imported by: 0

README

Sensor Sensibility Format

The Sensor Sensibility Format — or SSF for short — is a language agnostic format for transmitting observability data such as trace spans, metrics, events and more.

Why?

SSF is based on prior art of metrics formats and protocols mentioned in the inspiration section. Unlike each of these wonderful formats, which we have used for years and benefited greatly from, SSF is a binary format utilizing Protocol Buffers. It is emission-, collection- and storage-agnostic. It is merely a protocol for transmitting information. It is developed as part of a suite of technologies around Veneur.

Why A New Format?

Because we want to:

  • leverage protobuf so we no longer have to write buggy, string-based marshaling and unmarshaling code in clients libraries and server implementations
  • benefit from the efficiency of protobuf
  • collect and combine the great ideas from our inspiration
  • add some of our own ideas

Using SSF

  • You can send SSF as UDP packets to Veneur's ssf_listen_addresses.
  • Veneur can also read SSF as a wire protocol over connection protocols such as TCP or UNIX domain sockets
  • You can use the CLI tool veneur-emit.
  • You can use an SSF trace client in Go or Ruby.

Philosophy

We've got some novel ideas that we've put in to SSF. It might help to be familiar with the concepts in our inspiration. Here is our founding philosophy of SSF:

  • a timer is a span
  • a log line is a span, especially if it's structured
  • events are also spans
  • therefore, the core unit of all observability data is a span, or a unit of a trace.
    • spans might be single units, or units of a larger whole
  • other point metrics (e.g. counters and gauges) can be constituents of a span
    • it's more valuable to know the depth of a queue in the context of a span than alone
    • improve the context of counters and gauges, as they are part of a span
  • provide a format containing the superset of many backend's features

Inspiration

We build on the shoulders of giants, and are proud to have used and been inspired by these marvelous tools:

Documentation

Overview

Package ssf is a generated protocol buffer package.

It is generated from these files: 

ssf/sample.proto

It has these top-level messages: 

SSFSample
SSFSpan

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidLengthSample = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowSample   = fmt.Errorf("proto: integer overflow")
)
View Source 
var SSFSample_Metric_name = map[int32]string{
	0: "COUNTER",
	1: "GAUGE",
	2: "HISTOGRAM",
	3: "SET",
	4: "STATUS",
}
View Source 
var SSFSample_Metric_value = map[string]int32{
	"COUNTER":   0,
	"GAUGE":     1,
	"HISTOGRAM": 2,
	"SET":       3,
	"STATUS":    4,
}
View Source 
var SSFSample_Status_name = map[int32]string{
	0: "OK",
	1: "WARNING",
	2: "CRITICAL",
	3: "UNKNOWN",
}
View Source 
var SSFSample_Status_value = map[string]int32{
	"OK":       0,
	"WARNING":  1,
	"CRITICAL": 2,
	"UNKNOWN":  3,
}

Functions

This section is empty.

Types

type SSFSample 

type SSFSample struct {
	// The underlying type of the metric
	Metric SSFSample_Metric `protobuf:"varint,1,opt,name=metric,proto3,enum=ssf.SSFSample_Metric" json:"metric,omitempty"`
	// no spaces, but . is allowed
	// e.g.: veneur.bar.baz
	Name       string            `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
	Value      float32           `protobuf:"fixed32,3,opt,name=value,proto3" json:"value,omitempty"`
	Timestamp  int64             `protobuf:"varint,4,opt,name=timestamp,proto3" json:"timestamp,omitempty"`
	Message    string            `protobuf:"bytes,5,opt,name=message,proto3" json:"message,omitempty"`
	Status     SSFSample_Status  `protobuf:"varint,6,opt,name=status,proto3,enum=ssf.SSFSample_Status" json:"status,omitempty"`
	SampleRate float32           `protobuf:"fixed32,7,opt,name=sample_rate,json=sampleRate,proto3" json:"sample_rate,omitempty"`
	Tags       map[string]string `` /* 142-byte string literal not displayed */
	Unit       string            `protobuf:"bytes,9,opt,name=unit,proto3" json:"unit,omitempty"`
}

func Count 

func Count(name string, value float32, tags map[string]string, opts ...SampleOption) *SSFSample

Count returns an SSFSample representing an increment / decrement of a counter. It's a convenience wrapper around constructing SSFSample objects.

func Gauge 

func Gauge(name string, value float32, tags map[string]string, opts ...SampleOption) *SSFSample

Gauge returns an SSFSample representing a gauge at a certain value. It's a convenience wrapper around constructing SSFSample objects.

func Histogram 

func Histogram(name string, value float32, tags map[string]string, opts ...SampleOption) *SSFSample

Histogram returns an SSFSample representing a value on a histogram, like a timer or other range. It's a convenience wrapper around constructing SSFSample objects.

func Timing 

func Timing(name string, value time.Duration, resolution time.Duration, tags map[string]string, opts ...SampleOption) *SSFSample

Timing returns an SSFSample (really a histogram) representing the timing in the given resolution.

func (*SSFSample) Descriptor 

func (*SSFSample) Descriptor() ([]byte, []int)

func (*SSFSample) GetMessage 

func (m *SSFSample) GetMessage() string

func (*SSFSample) GetMetric 

func (m *SSFSample) GetMetric() SSFSample_Metric

func (*SSFSample) GetName 

func (m *SSFSample) GetName() string

func (*SSFSample) GetSampleRate 

func (m *SSFSample) GetSampleRate() float32

func (*SSFSample) GetStatus 

func (m *SSFSample) GetStatus() SSFSample_Status

func (*SSFSample) GetTags 

func (m *SSFSample) GetTags() map[string]string

func (*SSFSample) GetTimestamp 

func (m *SSFSample) GetTimestamp() int64

func (*SSFSample) GetUnit 

func (m *SSFSample) GetUnit() string

func (*SSFSample) GetValue added in v1.5.0 

func (m *SSFSample) GetValue() float32

func (*SSFSample) Marshal added in v1.6.0 

func (m *SSFSample) Marshal() (dAtA []byte, err error)

func (*SSFSample) MarshalTo added in v1.6.0 

func (m *SSFSample) MarshalTo(dAtA []byte) (int, error)

func (*SSFSample) ProtoMessage 

func (*SSFSample) ProtoMessage()

func (*SSFSample) Reset 

func (m *SSFSample) Reset()

func (*SSFSample) Size added in v1.6.0 

func (m *SSFSample) Size() (n int)

func (*SSFSample) String 

func (m *SSFSample) String() string

func (*SSFSample) Unmarshal added in v1.6.0 

func (m *SSFSample) Unmarshal(dAtA []byte) error

type SSFSample_Metric 

type SSFSample_Metric int32
const (
	SSFSample_COUNTER   SSFSample_Metric = 0
	SSFSample_GAUGE     SSFSample_Metric = 1
	SSFSample_HISTOGRAM SSFSample_Metric = 2
	SSFSample_SET       SSFSample_Metric = 3
	SSFSample_STATUS    SSFSample_Metric = 4
)

func (SSFSample_Metric) EnumDescriptor 

func (SSFSample_Metric) EnumDescriptor() ([]byte, []int)

func (SSFSample_Metric) String 

func (x SSFSample_Metric) String() string

type SSFSample_Status 

type SSFSample_Status int32
const (
	SSFSample_OK       SSFSample_Status = 0
	SSFSample_WARNING  SSFSample_Status = 1
	SSFSample_CRITICAL SSFSample_Status = 2
	SSFSample_UNKNOWN  SSFSample_Status = 3
)

func (SSFSample_Status) EnumDescriptor 

func (SSFSample_Status) EnumDescriptor() ([]byte, []int)

func (SSFSample_Status) String 

func (x SSFSample_Status) String() string

type SSFSpan added in v1.5.0 

type SSFSpan struct {
	Version int32 `protobuf:"varint,1,opt,name=version,proto3" json:"version,omitempty"`
	// the trace_id is the (span) id of the root span
	TraceId int64 `protobuf:"varint,2,opt,name=trace_id,json=traceId,proto3" json:"trace_id,omitempty"`
	// the id for this span
	Id int64 `protobuf:"varint,3,opt,name=id,proto3" json:"id,omitempty"`
	// the (span) id of the direct parent, if this span is not a root
	// span
	ParentId       int64 `protobuf:"varint,4,opt,name=parent_id,json=parentId,proto3" json:"parent_id,omitempty"`
	StartTimestamp int64 `protobuf:"varint,5,opt,name=start_timestamp,json=startTimestamp,proto3" json:"start_timestamp,omitempty"`
	EndTimestamp   int64 `protobuf:"varint,6,opt,name=end_timestamp,json=endTimestamp,proto3" json:"end_timestamp,omitempty"`
	// This flag being true signals that this span was an error. That definition
	// of error is not implicitly fatal, as a span may error but be fixed by
	// a subsequent retry, etc.
	Error bool `protobuf:"varint,7,opt,name=error,proto3" json:"error,omitempty"`
	// The name of the service
	// e.g. "veneur"
	Service string       `protobuf:"bytes,8,opt,name=service,proto3" json:"service,omitempty"`
	Metrics []*SSFSample `protobuf:"bytes,10,rep,name=metrics" json:"metrics,omitempty"`
	// Tags are name value pairs that describe a facet of the span. They apply to
	// the *entire* span as opposed to logs which apply to a specific time in
	// the span.
	Tags map[string]string `` /* 143-byte string literal not displayed */
	// An indicator span is one that represents an action that is included in a
	// service's Service Level Indicators (https://en.wikipedia.org/wiki/Service_level_indicator)
	// This is a signal to receivers that this span may be used to compute SLIs.
	// In practice a service's core feature — the thing you would "bill" for, such
	// as an API call or read/write operation — would be flagged as an indicator
	// span, and its child spans would further describe its duration.
	// It's also worth nothing that an indicator need not be the "root" or first
	// span in a trace. You might have various forms of middleware that happen
	// first or you might have multiple services participating in the same trace.
	Indicator bool `protobuf:"varint,12,opt,name=indicator,proto3" json:"indicator,omitempty"`
	// What to call this span. This could take the form of the endpoint
	// (/customer/:id), the function (class::name.method), a friendly name
	// (foo middleware) or whatever makes sense in your context.
	Name string `protobuf:"bytes,13,opt,name=name,proto3" json:"name,omitempty"`
}

SSFSpan is the primary unit of reporting in SSF. It embeds a set of SSFSamples, as well as start/stop time stamps and a parent ID (which allows assembling a span lineage for distributed tracing purposes).

Note that since this is protobuf, an SSFSpan does not *have* to include metrics, just as it does not *have* to include information necessary to reconstruct a trace.

Compatibility

On ingestion, an SSFSpan with an empty string for a name field but a tag "name" will have that name field replaced with the name tag, and the tag is removed.

Metric SSFSamples with a zero sample_rate (indicating it was left out) have the sample_rate field set to 1 on ingestion.

Validity Criteria

Programs consuming SSFSpans should take care to only process spans and metrics that fulfill the following criteria:

Metrics are considered valid if they have a name and a value.

SSFSpans are considered valid trace spans if they have non-zero id, trace_id, start_timestamp and end_timestamp fields.

func (*SSFSpan) Descriptor added in v1.5.0 

func (*SSFSpan) Descriptor() ([]byte, []int)

func (*SSFSpan) GetEndTimestamp added in v1.5.0 

func (m *SSFSpan) GetEndTimestamp() int64

func (*SSFSpan) GetError added in v1.5.0 

func (m *SSFSpan) GetError() bool

func (*SSFSpan) GetId added in v1.5.0 

func (m *SSFSpan) GetId() int64

func (*SSFSpan) GetIndicator added in v1.6.0 

func (m *SSFSpan) GetIndicator() bool

func (*SSFSpan) GetMetrics added in v1.5.0 

func (m *SSFSpan) GetMetrics() []*SSFSample

func (*SSFSpan) GetName added in v1.6.0 

func (m *SSFSpan) GetName() string

func (*SSFSpan) GetParentId added in v1.5.0 

func (m *SSFSpan) GetParentId() int64

func (*SSFSpan) GetService added in v1.5.0 

func (m *SSFSpan) GetService() string

func (*SSFSpan) GetStartTimestamp added in v1.5.0 

func (m *SSFSpan) GetStartTimestamp() int64

func (*SSFSpan) GetTags added in v1.5.0 

func (m *SSFSpan) GetTags() map[string]string

func (*SSFSpan) GetTraceId added in v1.5.0 

func (m *SSFSpan) GetTraceId() int64

func (*SSFSpan) GetVersion added in v1.5.0 

func (m *SSFSpan) GetVersion() int32

func (*SSFSpan) Marshal added in v1.6.0 

func (m *SSFSpan) Marshal() (dAtA []byte, err error)

func (*SSFSpan) MarshalTo added in v1.6.0 

func (m *SSFSpan) MarshalTo(dAtA []byte) (int, error)

func (*SSFSpan) ProtoMessage added in v1.5.0 

func (*SSFSpan) ProtoMessage()

func (*SSFSpan) Reset added in v1.5.0 

func (m *SSFSpan) Reset()

func (*SSFSpan) Size added in v1.6.0 

func (m *SSFSpan) Size() (n int)

func (*SSFSpan) String added in v1.5.0 

func (m *SSFSpan) String() string

func (*SSFSpan) Unmarshal added in v1.6.0 

func (m *SSFSpan) Unmarshal(dAtA []byte) error

type SampleOption 

type SampleOption func(*SSFSample)

SampleOption is a functional option that can be used for less commonly needed fields in sample creation helper functions.

func TimeUnit 

func TimeUnit(resolution time.Duration) SampleOption

TimeUnit sets the unit on a sample to the given resolution's SI unit symbol. Valid resolutions are the time duration constants from Nanosecond through Hour. The non-SI units "minute" and "hour" are represented by "min" and "h" respectively.

If a resolution is passed that does not correspond exactly to the duration constants in package time, this option does not affect the sample at all.

func Timestamp 

func Timestamp(ts time.Time) SampleOption

Timestamp is a functional option for creating an SSFSample. It sets the timestamp field on the sample to the timestamp passed.

func Unit 

func Unit(name string) SampleOption

Unit is a functional option for creating an SSFSample. It sets the sample's unit name to the name passed.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.