trace

package
v9.0.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2018 License: MIT Imports: 26 Imported by: 153

README

Trace

Veneur provides an experimental API for tracing requests between hosts. The API is in an experimental state and is subject to change.

The main Veneur tracing API is defined in the trace.go file; however, an OpenTracing compatibility layer is provided for convenience as well. These are functionally equivalent, though it is recommended not to mix the functions. (In other words, if a trace is started using Veneur's tracing API, avoid using the OpenTracing API functions on it or future children).

Eventually, these two interfaces will be consolidated.

Documentation

Overview

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.

Index

Examples

Constants

View Source 
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.

View Source 
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.

View Source 
const DefaultCapacity = 64

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

View Source 
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.

View Source 
const DefaultMaxBackoff = 1 * time.Second

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

View Source 
const DefaultParallelism = 8

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

View Source 
const DefaultVeneurAddress string = "udp://127.0.0.1:8128"

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

View Source 
const ResourceKey = "resource"

Experimental

Variables

View Source 
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.

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

ErrNoClient indicates that no client is yet initialized.

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

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

View Source 
var GlobalTracer = Tracer{}

GlobalTracer is the… global tracer!

View Source 
var HeaderFormats = []HeaderGroup{

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

	HeaderGroup{
		TraceID: "Trace-Id",
		SpanID:  "Span-Id",
	},

	HeaderGroup{
		TraceID: "X-Trace-Id",
		SpanID:  "X-Span-Id",
	},

	HeaderGroup{
		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.

View Source 
var Service = ""

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

Functions

func Buffered added in v1.7.0 

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 added in v1.2.0 

func Disable()

(Experimental) Disabled sets tracing to disabled.

func Disabled 

func Disabled() bool

func Enable added in v1.2.0 

func Enable()

(Experimental) Enabled sets tracing to enabled.

func Flush added in v1.7.0 

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 added in v1.7.0 

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 added in v1.9.0 

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 added in v1.7.0 

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 added in v1.9.0 

func SendClientStatistics(cl *Client, stats *statsd.Client, 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 added in v1.9.0 

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.

Types

type Client added in v1.7.0 

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).

Structure

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 added in v1.8.0 

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 added in v1.9.0 

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 added in v1.7.0 

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.

Example

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

package main

import (
	"github.com/stripe/veneur/trace"
)

func main() {
	// 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 {
		panic(err)
	}

	// Replace the old client:
	trace.SetDefaultClient(cl)
}

Output:

func (*Client) Close added in v1.7.0 

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 added in v1.8.0 

type ClientBackend interface {
	io.Closer

	// 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 added in v1.7.0 

type ClientParam func(*Client) error

ClientParam is an option for NewClient. Its implementation borrows from Dave Cheney's functional options API (https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis).

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 added in v1.7.0 

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 added in v1.7.0 

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 added in v1.7.0 

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 added in v1.7.0 

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 added in v1.9.0 

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 added in v1.9.0 

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 added in v1.7.0 

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 added in v1.9.0 

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 added in v1.9.0 

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 

type ErrContractViolation struct {
	// contains filtered or unexported fields
}

func (ErrContractViolation) Error 

func (e ErrContractViolation) Error() string

type FlushError added in v1.9.0 

type FlushError struct {
	Errors []error
}

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

func (*FlushError) Error added in v1.9.0 

func (fe *FlushError) Error() string

type FlushableClientBackend added in v1.9.0 

type FlushableClientBackend interface {
	ClientBackend

	// 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 added in v1.8.0 

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 

type Span struct {
	*Trace
	// contains filtered or unexported fields
}

Span is a member of a trace

func StartSpanFromContext 

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 

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

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

func (*Span) BaggageItem 

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

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

func (*Span) ClientFinish added in v1.7.0 

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

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

func (*Span) ClientFinishWithOptions added in v1.7.0 

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 

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

func (*Span) Finish 

func (s *Span) Finish()

Finish ends a trace end records it with DefaultClient.

func (*Span) FinishWithOptions 

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 

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 

func (s *Span) LogEvent(event string)

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

func (*Span) LogEventWithPayload 

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 

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 

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

func (*Span) SetBaggageItem 

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

SetBaggageItem sets the value of a baggage in the span.

func (*Span) SetOperationName 

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

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

func (*Span) SetTag 

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

SetTag sets the tags on the underlying span

func (*Span) Tracer 

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

Tracer returns the tracer that created this Span

type Trace 

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 foo.bar.baz
	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 (https://en.wikipedia.org/wiki/Service_level_indicator)
	// For more information, see the SSF definition at https://github.com/stripe/veneur/tree/master/ssf
	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 

func SpanFromContext(c context.Context) *Trace

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

func StartChildSpan 

func StartChildSpan(parent *Trace) *Trace

StartChildSpan creates a new Span with the specified parent

func StartTrace 

func StartTrace(resource string) *Trace

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

func (*Trace) Add added in v1.9.0 

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

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

Example 
package main

import (
	"context"
	"time"

	"github.com/stripe/veneur/ssf"
	"github.com/stripe/veneur/trace"
)

func main() {
	// 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))
}

Output:

func (*Trace) Attach 

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 added in v1.7.0 

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 

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 

func (t *Trace) Error(err error)

func (*Trace) ProtoMarshalTo 

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 

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 added in v1.5.0 

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 

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 

type Tracer struct {
}

Tracer is a tracer

func (Tracer) Extract 

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 

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 

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 added in v1.9.0 

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 

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 

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)

Source Files

View all Source files

Directories

Path Synopsis
Package metrics provides routines for conveniently reporting metrics attached to SSF spans.
 Package metrics provides routines for conveniently reporting metrics attached to SSF spans.

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.