trace

package
v13.2.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2020 License: MIT Imports: 25 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 API for initiating and reporting SSF traces and attaching spans to them. Veneur's tracing API also provides an experimental opentracing compatibility layer.

The Veneur tracing API is mostly independent of the opentracing compatibility layer, however OpenTracing compatibility may be removed in a future release.

Setup and Structure of the API

To use the API, user code must set its service name via the global variable Service, which is used by trace visualization tools to tell apart the spans reported by different services. Code using the trace API must set its Service, and set it only once, in the application's main package, ideally in the init() function: 

trace.Service = "my-awesome-service"

The trace API makes heavy use of the go stdlib's Contexts and is built on three abstractions: the Client, the ClientBackend and the Span.

Contexts

Since it is very common for networked code to use the go stdlib's Context interface, veneur's trace API is designed to be used together with Contexts. The API uses Contexts to store the current Span, and will automatically pick the appropriate parent span from the Context.

To effectively use the trace API, user code needs to ensure that all functions that communicate externally (which includes using traces) take Contexts as parameters, and pass them down.

See https://blog.golang.org/context for an introduction to using Context.

Spans

Spans represent the duration of a "unit of work" in a system: They have a start and an end time, a name, and additional data that can help identify what the work was. Example units of work could be the handling of an HTTP request, or a database read. For convenience, it is usually easiest to have a span represent a single function to delineate the start and end, which makes it easy to create the Span and report it via a defer statement.

To create a new Span, use StartSpanFromContext. This function will create a Span with a parent ID pointing to the to the trace that came before it in the Context. Typically, users should pass "" as the name to let StartSpanFromContext figure out the correct name from caller information. 

span, ctx := trace.StartSpanFromContext(ctx, "")
// report the span with the default client when this function returns:
defer span.Finish()
... // do work here

Reporting Spans via the trace Client

Once constructed, SSF Spans must be reported to a system that processes them. To do that, package trace exports a trace Client. Typical applications should use the DefaultClient exposed by this package. By default, it is set up to send spans to veneur listening on the default SSF UDP port, 8128. An application can use SetDefaultClient to change the default client in its main package.

To allow testing an application's Span reporting behavior, it is desirable to take a Client argument in tested functions and report spans to that client explicitly: 

client := trace.DefaultClient
span, ctx := trace.StartSpanFromContext(ctx, "")
defer span.ClientFinish(client)

A value of nil is a supported zero value for a trace Client. It will submit no spans anywhere.

Client Backends

The trace Client can use various transports to send spans to a destination. It is the Backend's job to perform any necessary serialization.

Package trace exports some networked backends (sending protobuf-encoded SSF spans over UDP and UNIX domain sockets), and allows users to define their own ClientBackends, which can be useful in tests. See the ClientBackend interface's documentation for details.

The subpackage testbackend contains backend types that allows testing the trace behavior of applications. See the corresponding package documentation for details.

Additional information on Spans

There are several additional things that can be put on a Span: the most common ones are Errors, Tags and Samples. Spans can also be indicators. The following sections will talk about these in detail.

Error handling

Call span.Error with the error that caused a Span to fail. Different programs have different requirements for when a Span should be considered to have "failed". A typical rule of thumb is that if you have a traced function that returns an error and it would return an error, that function should also use span.Error. This way, anyone who views a trace visualization will be able to tell that an error happened there. To report an error, use the following: 

if err != nil {
        span.Error(err)
        return err
}

Tags

Spans can hold a map of name-value pairs (both strings) on their Tags field. These will be reported to trace visualization tools as indexed tags, so it should be possible to search for spans with the relevant information.

Note: a Span object, when created, will have a nil Tags map to reduce the number of unnecessary allocations. To add Tags to a Span, it is recommended to initialize the Tags object with a constructed map like so: 

span.Tags = map[string]string{
        "user_id": userID,
        "action": "booped",
}

Samples

Veneur's trace API supports attaching SSF Samples to Spans. These can be metrics, service checks or events. Veneur will extract them from the span and report them to any configured metrics provider.

In the future, veneur may add information that allows linking the extracted metrics to the spans on which they were reported.

See the ssf package and the trace/metrics package for details on using Samples effectively.

Indicator Spans

Typically, a traced service has some units of work that indicate how well a service is working. For example, a hypothetical HTTP-based payments API might have a charge endpoint. The time that an API call takes on that endpoint and its successes or failures can be used to extract service-level indicators (SLI) for latency, throughput and error rates.

Concretely, the veneur server privileges these Indicator Spans by doing exactly the above: It reports a timer metric tagged with the service name on the span, and an "error" tag set to "true" if the span had Error set.

To report an indicator span, use: 

span.Indicator = true

OpenTracing Compatibility

Package trace's data structure implement the OpenTracing interfaces. This allows users to apply all of OpenTracing's helper functions, e.g. to extract a Span from the context, use SpanFromContext and a type assertion: 

span, ok := opentracing.SpanFromContext(ctx).(*trace.Span)

See https://godoc.org/github.com/opentracing/opentracing-go for details on the OpenTracing API.

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 seconds. 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",

		OutgoingHeaders: map[string]string{
			"ot-tracer-sampled": "true",
		},
		// 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 must be set exactly once, by the main package. It is recommended to set this value in an init() function or at the beginning of the main() function.

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 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 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 NormalizeSamples 

func NormalizeSamples(normalizer func(*ssf.SSFSample)) ClientParam

NormalizeSamples takes a function that gets run on every SSFSample reported as part of a span. This allows conditionally adjusting tags or scopes on metrics that might exceed cardinality limits.

Note that the normalizer gets run on Samples every time the trace.Report function is called. This happen more than once, depending on the error handling behavior of the reporting program.

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

	OutgoingHeaders map[string]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 creates a span that fits into a span tree - child or root. It makes a new span, find a parent span if it exists on the context and fills in the data in the newly-created span to ensure a proper parent-child relationship (if no parent exists, is sets the new span up as a root Span, i.e., a Trace). Then StartSpanFromContext sets the newly-created span as the current span on a child Context. That child context is returned also.

Name inference

StartSpanFromContext takes a name argument. If passed "", it will infer the current function's name as the span name.

StartSpanFromContext is the recommended way to create trace spans in a program.

Example 
package main

import (
	"context"
	"fmt"

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

func main() {
	ctx := context.TODO() // assume your code gets a Context from somewhere

	// Create a span:
	span, ctx := trace.StartSpanFromContext(ctx, "")
	defer span.Finish()

	span.Tags = map[string]string{
		"operation": "example",
	}

	// Function name inference will have guessed the name of this
	// example: "trace_test.ExampleStartSpanFromContext"
	fmt.Println(span.Name)
}

Output:

trace_test.ExampleStartSpanFromContext

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 StatsCounter 

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 

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.

SpanFromContext is considered experimental. Prefer StartSpanFromContext instead.

Compatibility with OpenTracing

SpanFromContext behaves differently from opentracing.SpanFromContext: The opentracing function returns the exact span that is stored on the Context, but this function allocates a new span with a parent ID set to that of the span stored on 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

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.
Package testbackend contains helpers to make it easier to test the tracing behavior of code using veneur's trace API.
 Package testbackend contains helpers to make it easier to test the tracing behavior of code using veneur's trace API.

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.