veneur: Index | Examples | Files | Directories

package trace

import ""

Package trace provies an experimental API for initiating traces. Veneur's tracing API also provides an opentracing compatibility layer. The Veneur tracing API is completely independent of the opentracing compatibility layer, with the exception of one convenience function.



Package Files

backend.go client.go opentracing.go trace.go


const BufferSize int = int(protocol.MaxSSFPacketLength + protocol.SSFFrameLength)

BufferSize is the default size of the SSF buffer per connection. It defaults to enough bytes to accomodate the largest SSF span.

const DefaultBackoff = 20 * time.Millisecond

DefaultBackoff defaults to 10 milliseconds of initial wait time. Subsequent wait times will add this backoff to the time they wait.

const DefaultCapacity = 64

DefaultCapacity is the capacity of the span submission queue in a veneur client.

const DefaultConnectTimeout = 10 * time.Second

DefaultConnectTimeout is to 10 seconts. Any attempt to (re)connect to a veneur will take longer than this. If it would take longer, the span is discarded.

const DefaultMaxBackoff = 1 * time.Second

DefaultMaxBackoff defaults to 1 second. No reconnection attempt wait interval will be longer than this.

const DefaultParallelism = 8

DefaultParallelism is the number of span submission goroutines a veneur client runs in parallel.

const DefaultVeneurAddress string = "udp://"

DefaultVeneurAddress is the address that a reasonable veneur should listen on. Currently it defaults to UDP port 8128.

const ResourceKey = "resource"



var ErrClientNotNetworked = fmt.Errorf("client is not using a network backend")

ErrClientNotNetworked indicates that the client being constructed does not support options relevant only to networked clients.

var ErrNoClient = errors.New("client is not initialized")

ErrNoClient indicates that no client is yet initialized.

var ErrUnsupportedSpanContext = errors.New("Unsupported SpanContext")
var ErrWouldBlock = errors.New("sending span would block")

ErrWouldBlock indicates that a client is not able to send a span at the current time.

var GlobalTracer = Tracer{}

GlobalTracer is the… global tracer!

var HeaderFormats = []HeaderGroup{

        TraceID: "ot-tracer-traceid",
        SpanID:  "ot-tracer-spanid",
        // contains filtered or unexported fields

        TraceID: "Trace-Id",
        SpanID:  "Span-Id",

        TraceID: "X-Trace-Id",
        SpanID:  "X-Span-Id",

        TraceID: "Traceid",
        SpanID:  "Spanid",

Veneur supports multiple tracing header formats. We try each set of headers until we find one that exists. Note: textMapReaderGet is case insensitive, so the capitalization of these headers is not important.

var Service = ""

Service is our service name and should be set exactly once, at startup

func Buffered Uses

func Buffered(cl *Client) error

Buffered sets the client to be buffered with the default buffer size (enough to accomodate a single, maximum-sized SSF frame, currently about 16MB).

When using buffered clients, since buffers tend to be large and SSF packets are fairly small, it might appear as if buffered clients are not sending any spans at all.

Code using a buffered client should ensure that the client gets flushed in a reasonable interval, either by calling Flush manually in an appropriate goroutine, or by also using the FlushInterval functional option.

func Disable Uses

func Disable()

(Experimental) Disabled sets tracing to disabled.

func Disabled Uses

func Disabled() bool

func Enable Uses

func Enable()

(Experimental) Enabled sets tracing to enabled.

func Flush Uses

func Flush(cl *Client) error

Flush instructs a client to flush to the upstream veneur all the spans that were serialized up until the moment that the flush was received. It will wait until the flush is completed (including all reconnection attempts), and return any error caused by flushing the buffer.

Flush returns ErrNoClient if client is nil and ErrWouldBlock if the client is not able to take more requests.

func FlushAsync Uses

func FlushAsync(cl *Client, ch chan<- error) error

FlushAsync instructs a buffered client to flush to the upstream veneur all the spans that were serialized up until the moment that the flush was received. Once the client has completed the flush, any error (or nil) is sent down the error channel.

FlushAsync returns ErrNoClient if client is nil.

func NeutralizeClient Uses

func NeutralizeClient(client *Client)

NeutralizeClient sets up a client such that all Record or Flush operations result in ErrWouldBlock. It dashes all hope of a Client ever successfully recording or flushing spans, and is mostly useful in tests.

func Record Uses

func Record(cl *Client, span *ssf.SSFSpan, done chan<- error) error

Record instructs the client to serialize and send a span. It does not wait for a delivery attempt, instead the Client will send the result from serializing and submitting the span to the channel done, if it is non-nil.

Record returns ErrNoClient if client is nil and ErrWouldBlock if the client is not able to accomodate another span.

func SendClientStatistics Uses

func SendClientStatistics(cl *Client, stats StatsCounter, tags []string)

SendClientStatistics uses the client's recorded backpressure statistics (failed/successful flushes, failed/successful records) and reports them with the given statsd client, and resets the statistics to zero again.

func SetDefaultClient Uses

func SetDefaultClient(client *Client)

SetDefaultClient overrides the default client used for recording traces, and gracefully closes the existing one. This is not safe to run concurrently with other goroutines.

type Client Uses

type Client struct {
    // contains filtered or unexported fields

Client is a Client that sends traces to Veneur over the network. It represents a pump for span packets from user code to the network (whether it be UDP or streaming sockets, with or without buffers).


A Client is composed of two parts (each with its own purpose): A serialization part providing backpressure (the front end) and a backend (which is called on a single goroutine).

var DefaultClient *Client

DefaultClient is the client that trace recording happens on by default. If it is nil, no recording happens and ErrNoClient is returned from recording functions.

Note that it is not safe to set this variable concurrently with other goroutines that use the DefaultClient.

func NewBackendClient Uses

func NewBackendClient(b ClientBackend, opts ...ClientParam) (*Client, error)

NewBackendClient constructs and returns a Client sending to the ClientBackend passed. Most user code should use NewClient, as NewBackendClient is primarily useful for processing spans internally (e.g. in veneur itself or in test code), without making trips over the network.

func NewChannelClient Uses

func NewChannelClient(spanChan chan<- *ssf.SSFSpan, opts ...ClientParam) (*Client, error)

NewChannelClient constructs and returns a Client that can send directly into a span receiver channel. It provides an alternative interface to NewBackendClient for constructing internal and test-only clients.

func NewClient Uses

func NewClient(addrStr string, opts ...ClientParam) (*Client, error)

NewClient constructs a new client that will attempt to connect to addrStr (an address in veneur URL format) using the parameters in opts. It returns the constructed client or an error.

This demonstrates how to switch out an existing DefaultClient, closing the existing connection correctly.


// Create the new client first (we'll create one that can send
// 20 span packets in parallel):
cl, err := trace.NewClient(trace.DefaultVeneurAddress, trace.Capacity(20))
if err != nil {

// Replace the old client:

func (*Client) Close Uses

func (c *Client) Close() error

Close tears down the entire client. It waits until the backend has closed the network connection (if one was established) and returns any error from closing the connection.

type ClientBackend Uses

type ClientBackend interface {

    // SendSync synchronously sends a span to an upstream
    // veneur.
    // On a networked connection, if it encounters a protocol
    // error in sending, it must loop forever, backing off by
    // n*the backoff interval (until it reaches the maximal
    // backoff interval) and tries to reconnect. If SendSync
    // encounters any non-protocol errors (e.g. in serializing the
    // SSF span), it must return them without reconnecting.
    SendSync(ctx context.Context, span *ssf.SSFSpan) error

ClientBackend represents the ability of a client to transport SSF spans to a veneur server.

type ClientParam Uses

type ClientParam func(*Client) error

ClientParam is an option for NewClient. Its implementation borrows from Dave Cheney's functional options API (

Unless otherwise noted, ClientParams only apply to networked backends (i.e., those used by NewClient). Using them on non-network-backed clients will return ErrClientNotNetworked on client creation.

func BackoffTime Uses

func BackoffTime(t time.Duration) ClientParam

BackoffTime sets the time increment that backoff time is increased (linearly) between every reconnection attempt the backend makes. If this option is not used, the backend uses DefaultBackoff.

func BufferedSize Uses

func BufferedSize(size uint) ClientParam

BufferedSize indicates that a client should have a buffer size bytes large. See the note on the Buffered option about flushing the buffer.

func Capacity Uses

func Capacity(n uint) ClientParam

Capacity indicates how many spans a client's channel should accommodate. This parameter can be used on both generic and networked backends.

func ConnectTimeout Uses

func ConnectTimeout(t time.Duration) ClientParam

ConnectTimeout sets the maximum total amount of time a client backend spends trying to establish a connection to a veneur. If a connection can not be established after this timeout has expired (counting from the time the connection is first attempted), the span is discarded. If this option is not used, the backend uses DefaultConnectTimeout.

func FlushChannel Uses

func FlushChannel(ch <-chan time.Time, stop func()) ClientParam

FlushChannel sets up a buffered client to perform one synchronous flush any time the given channel has a Time element ready. When the Client is closed, FlushWith invokes the passed stop function.

This functional option is mostly useful for tests; code intended to be used in production should rely on FlushInterval instead, as time.Ticker is set up to deal with slow flushes.

func FlushInterval Uses

func FlushInterval(interval time.Duration) ClientParam

FlushInterval sets up a buffered client to perform one synchronous flush per time interval in a new goroutine. The goroutine closes down when the Client's Close method is called.

This uses a time.Ticker to trigger the flush, so will not trigger multiple times if flushing should be slower than the trigger interval.

func MaxBackoffTime Uses

func MaxBackoffTime(t time.Duration) ClientParam

MaxBackoffTime sets the maximum time duration waited between reconnection attempts. If this option is not used, the backend uses DefaultMaxBackoff.

func ParallelBackends Uses

func ParallelBackends(nBackends uint) ClientParam

ParallelBackends sets the number of parallel network backend connections to send spans with. Each backend holds a connection to an SSF receiver open.

func ReportStatistics Uses

func ReportStatistics(stats *statsd.Client, interval time.Duration, tags []string) ClientParam

ReportStatistics sets up a goroutine that periodically (at interval) sends statistics about backpressure experienced on the client to a statsd server.

type ErrContractViolation Uses

type ErrContractViolation struct {
    // contains filtered or unexported fields

func (ErrContractViolation) Error Uses

func (e ErrContractViolation) Error() string

type FlushError Uses

type FlushError struct {
    Errors []error

FlushError is an aggregate error type indicating that one or more backends failed to flush.

func (*FlushError) Error Uses

func (fe *FlushError) Error() string

type FlushableClientBackend Uses

type FlushableClientBackend interface {

    // FlushSync causes all (potentially) buffered data to be sent to
    // the upstream veneur.
    FlushSync(ctx context.Context) error

FlushableClientBackend represents the ability of a client to flush any buffered SSF spans over to a veneur server.

type HeaderGroup Uses

type HeaderGroup struct {
    TraceID string
    SpanID  string
    // contains filtered or unexported fields

Lists the names of headers that a specification uses for representing trace information.

type Span Uses

type Span struct {
    // contains filtered or unexported fields

Span is a member of a trace

func StartSpanFromContext Uses

func StartSpanFromContext(ctx context.Context, name string, opts ...opentracing.StartSpanOption) (s *Span, c context.Context)

StartSpanFromContext is used to create a child span when the parent trace is in the context

func (*Span) Attach Uses

func (s *Span) Attach(ctx context.Context) context.Context

Attach attaches the span to the context. It delegates to opentracing.ContextWithSpan

func (*Span) BaggageItem Uses

func (s *Span) BaggageItem(restrictedKey string) string

BaggageItem fetches the value of a baggage item in the span.

func (*Span) ClientFinish Uses

func (s *Span) ClientFinish(cl *Client)

ClientFinish ends a trace and records it with the given Client.

func (*Span) ClientFinishWithOptions Uses

func (s *Span) ClientFinishWithOptions(cl *Client, opts opentracing.FinishOptions)

ClientFinishWithOptions finishes the span and records it on the given client, but with explicit control over timestamps and log data. The BulkLogData field is deprecated and ignored.

func (*Span) Context Uses

func (s *Span) Context() opentracing.SpanContext

func (*Span) Finish Uses

func (s *Span) Finish()

Finish ends a trace end records it with DefaultClient.

func (*Span) FinishWithOptions Uses

func (s *Span) FinishWithOptions(opts opentracing.FinishOptions)

FinishWithOptions finishes the span, but with explicit control over timestamps and log data. The BulkLogData field is deprecated and ignored.

func (*Span) Log Uses

func (s *Span) Log(data opentracing.LogData)

Log is deprecated and unimplemented. It is included only to satisfy the opentracing.Span interface.

func (*Span) LogEvent Uses

func (s *Span) LogEvent(event string)

LogEvent is deprecated and unimplemented. It is included only to satisfy the opentracing.Span interface.

func (*Span) LogEventWithPayload Uses

func (s *Span) LogEventWithPayload(event string, payload interface{})

LogEventWithPayload is deprecated and unimplemented. It is included only to satisfy the opentracing.Span interface.

func (*Span) LogFields Uses

func (s *Span) LogFields(fields ...opentracinglog.Field)

LogFields sets log fields on the underlying span. Currently these are ignored, but they can be fun to set anyway!

func (*Span) LogKV Uses

func (s *Span) LogKV(alternatingKeyValues ...interface{})

func (*Span) SetBaggageItem Uses

func (s *Span) SetBaggageItem(restrictedKey, value string) opentracing.Span

SetBaggageItem sets the value of a baggage in the span.

func (*Span) SetOperationName Uses

func (s *Span) SetOperationName(name string) opentracing.Span

SetOperationName sets the name of the operation being performed in this span.

func (*Span) SetTag Uses

func (s *Span) SetTag(key string, value interface{}) opentracing.Span

SetTag sets the tags on the underlying span

func (*Span) Tracer Uses

func (s *Span) Tracer() opentracing.Tracer

Tracer returns the tracer that created this Span

type StatsCounter Uses

type StatsCounter interface {
    Count(metric string, n int64, tags []string, rate float64) error

StatsCounter is an interface corresponding to statsd's. It's useful for stubbing in tests to validate the right statistics get sent.

type Trace Uses

type Trace struct {
    // the ID for the root span
    // which is also the ID for the trace itself
    TraceID int64

    // For the root span, this will be equal
    // to the TraceId
    SpanID int64

    // For the root span, this will be <= 0
    ParentID int64

    // The Resource should be the same for all spans in the same trace
    Resource string

    Start time.Time

    End time.Time

    // If non-zero, the trace will be treated
    // as an error
    Status ssf.SSFSample_Status

    Tags map[string]string

    // Unlike the Resource, this should not contain spaces
    // It should be of the format
    Name string

    // Sent holds a channel. If set, this channel receives an
    // error (or nil) when the span has been serialized and sent.
    Sent chan<- error

    // Samples holds a list of samples / metrics to be reported
    // alongside a span.
    Samples []*ssf.SSFSample

    // An indicator span is one that represents an action that is included in a
    // service's Service Level Indicators (
    // For more information, see the SSF definition at
    Indicator bool
    // contains filtered or unexported fields

Trace is a convenient structural representation of a TraceSpan. It is intended to map transparently to the more general type SSFSample.

func SpanFromContext Uses

func SpanFromContext(c context.Context) *Trace

SpanFromContext is used to create a child span when the parent trace is in the context

func StartChildSpan Uses

func StartChildSpan(parent *Trace) *Trace

StartChildSpan creates a new Span with the specified parent

func StartTrace Uses

func StartTrace(resource string) *Trace

StartTrace is called by to create the root-level span for a trace

func (*Trace) Add Uses

func (t *Trace) Add(samples ...*ssf.SSFSample)

Add adds a number of metrics/samples to a Trace.


// Create a span for testing and ensure it gets reported:
span, _ := trace.StartSpanFromContext(context.Background(), "an_example")
defer span.Finish()

// Add a counter:
span.Add(ssf.Count("hey.there", 1, map[string]string{
    "a.tag": "a value",
// Add a timer:
span.Add(ssf.Timing("some.duration", 3*time.Millisecond, time.Nanosecond, nil))

func (*Trace) Attach Uses

func (t *Trace) Attach(c context.Context) context.Context

Attach attaches the current trace to the context and returns a copy of the context with that trace stored under the key "trace".

func (*Trace) ClientRecord Uses

func (t *Trace) ClientRecord(cl *Client, name string, tags map[string]string) error

ClientRecord uses the given client to send a trace to a veneur instance.

func (*Trace) Duration Uses

func (t *Trace) Duration() time.Duration

Duration is a convenience function for the difference between the Start and End timestamps. It assumes the span has already ended.

func (*Trace) Error Uses

func (t *Trace) Error(err error)

func (*Trace) ProtoMarshalTo Uses

func (t *Trace) ProtoMarshalTo(w io.Writer) error

ProtoMarshalTo writes the Trace as a protocol buffer in text format to the specified writer.

func (*Trace) Record Uses

func (t *Trace) Record(name string, tags map[string]string) error

Record sends a trace to a veneur instance using the DefaultClient .

func (*Trace) SSFSpan Uses

func (t *Trace) SSFSpan() *ssf.SSFSpan

SSFSpan converts the Trace to an SSFSpan type. It sets the duration, so it assumes the span has already ended. (It is safe to call on a span that has not ended, but the duration field will be invalid)

func (*Trace) SetParent Uses

func (t *Trace) SetParent(parent *Trace)

SetParent updates the ParentId, TraceId, and Resource of a trace based on the parent's values (SpanId, TraceId, Resource).

type Tracer Uses

type Tracer struct {

Tracer is a tracer

func (Tracer) Extract Uses

func (t Tracer) Extract(format interface{}, carrier interface{}) (ctx opentracing.SpanContext, err error)

Extract returns a SpanContext given the format and the carrier. The SpanContext returned represents the parent span (ie, SpanId refers to the parent span's own SpanId). TODO support all the BuiltinFormats

func (Tracer) ExtractRequestChild Uses

func (tracer Tracer) ExtractRequestChild(resource string, req *http.Request, name string) (*Span, error)

ExtractRequestChild extracts a span from an HTTP request and creates and returns a new child of that span

func (Tracer) Inject Uses

func (t Tracer) Inject(sm opentracing.SpanContext, format interface{}, carrier interface{}) (err error)

Inject injects the provided SpanContext into the carrier for propagation. It will return opentracing.ErrUnsupportedFormat if the format is not supported. TODO support other SpanContext implementations TODO support all the BuiltinFormats

func (Tracer) InjectHeader Uses

func (tracer Tracer) InjectHeader(t *Trace, h http.Header) error

InjectHeader injects a trace into an HTTP header. It is a convenience function for Inject.

func (Tracer) InjectRequest Uses

func (tracer Tracer) InjectRequest(t *Trace, req *http.Request) error

InjectRequest injects a trace into an HTTP request header. It is a convenience function for Inject.

func (Tracer) StartSpan Uses

func (t Tracer) StartSpan(operationName string, opts ...opentracing.StartSpanOption) opentracing.Span

StartSpan starts a span with the specified operationName (name) and options. If the options specify a parent span and/or root trace, the name from the root trace will be used. The value returned is always a concrete Span (which satisfies the opentracing.Span interface)


metricsPackage metrics provides routines for conveniently reporting metrics attached to SSF spans.
testbackendPackage testbackend contains helpers to make it easier to test the tracing behavior of code using veneur's trace API.

Package trace imports 26 packages (graph) and is imported by 29 packages. Updated 2018-11-30. Refresh now. Tools for package owners.