spans

Documentation

Index

• Constants
• Variables
• func ContextStoreSpan(ctx context.Context, span Factory) context.Context
• func FinishSpan(span Factory)
• func HexSpanID(spanID uint64) string
• func IsValidTraceID(s string) bool
• func NonHexIndex(s string) int
• type Factory
  • func ContextGetSpan(ctx context.Context) Factory
• type ROSpan
  • func NewROSpan(projectID string) ROSpan
  • func (s ROSpan) AddAttribute(_ string, _ interface{}) error
  • func (s ROSpan) Finish() time.Duration
  • func (s ROSpan) GetCloudContext() string
  • func (s ROSpan) GetProjectID() string
  • func (s ROSpan) GetSpanID() uint64
  • func (s ROSpan) GetSpanPath() string
  • func (s ROSpan) GetStart() time.Time
  • func (s ROSpan) GetTraceID() string
  • func (s ROSpan) GetTracePath() string
  • func (s ROSpan) Import(traceID string, spanID uint64) (Factory, error)
  • func (s ROSpan) ImportFromHeaders(headers http.Header) Factory
  • func (s ROSpan) NewSpan() Factory
  • func (s ROSpan) NewSubSpan() Factory
  • func (s ROSpan) NewTrace() Factory
  • func (s ROSpan) SetDisplayName(_ string)
  • func (s ROSpan) SetHeader(headers http.Header)
  • func (s ROSpan) SetIsClient()
  • func (s ROSpan) SetIsPublisher()
  • func (s ROSpan) SetIsServer()
  • func (s ROSpan) SetIsSubscriber()
  • func (s *ROSpan) SetSpanID(spanID uint64)
  • func (s ROSpan) SetStatusCode(_ int64)
  • func (s ROSpan) SetStatusMessage(_ string)

Constants

const TraceHeader = "X-Cloud-Trace-Context"

Variables

var HexChars = [8]uint32{0, 0x3ff0000, 0x7e, 0x7e, 0, 0, 0, 0}

HexChars is a 256-bit value that has a 1 bit at the offset of the ASCII values of '0'..'9', 'a'..'f', and 'A'..'F', the hexidecimal digits.

Functions

func ContextStoreSpan

func ContextStoreSpan(ctx context.Context, span Factory) context.Context

func FinishSpan

func FinishSpan(span Factory)

FinishSpan() calls Finish() on the passed-in 'span', unless it is 'nil'. It is meant to be used with 'defer' when a 'span' might be 'nil':

defer spans.FinishSpan(span)

func HexSpanID

func HexSpanID(spanID uint64) string

func IsValidTraceID

func IsValidTraceID(s string) bool

IsValidTraceID() returns 'true' only if 's' is a non-zero hexadecimal value of 32 digits.

func NonHexIndex

func NonHexIndex(s string) int

NonHexIndex() returns the offset to the first character in the string that is not a hexadecimal digit (0..9, a..f, A..F) or -1 if none.

Types

type Factory

type Factory interface {

	// GetProjectID() retuns the GCP Project ID (which is not the Project
	// Number) for which spans will be registered.
	//
	GetProjectID() string

	// GetTraceID() retuns "" if the factory is empty.  Otherwise it returns
	// the trace ID of the contained span (which will not be "" nor a
	// hexadecimal representation of 0).
	//
	GetTraceID() string

	// GetSpanID() retuns 0 if the factory is empty.  Otherwise it returns
	// the span ID of the contained span (which will not be 0).
	//
	GetSpanID() uint64

	// GetStart() returns the time at which the span began.  Returns a zero
	// time if the factory is empty or the contained span was Import()ed.
	//
	GetStart() time.Time

	// GetTracePath() returns "" if the factory is empty.  Otherwise it
	// returns the trace's resource sub-path which will be in the form
	// "projects/{projectID}/traces/{traceID}".
	//
	GetTracePath() string

	// GetSpanPath() returns "" if the factory is empty.  Otherwise it
	// returns the span's resource sub-path which will be in the form
	// "traces/{traceID}/spans/{spanID}" where both IDs are in hexadecimal.
	//
	GetSpanPath() string

	// GetCloudContext() returns "" if the factory is empty.  Otherwise it
	// returns a value appropriate for the "X-Cloud-Trace-Context:" header
	// which will be in the form "{traceID}/{spanID}" where spanID is in
	// base 10.
	//
	GetCloudContext() string

	// Import() returns a new factory containing a span created somewhere
	// else.  If the traceID or spanID is invalid, then a 'nil' factory and
	// an error are returned.  The usual reason to do this is so that you can
	// then call NewSubSpan().
	//
	Import(traceID string, spanID uint64) (Factory, error)

	// ImportFromHeaders() returns a new factory containing a span created
	// somewhere else based on the "X-Cloud-Trace-Context:" header.  If the
	// header does not contain a valid CloudContext value, then a valid but
	// empty factory is returned.
	//
	ImportFromHeaders(headers http.Header) Factory

	// SetHeader() sets the "X-Cloud-Trace-Context:" header if the factory
	// is not empty.
	//
	SetHeader(headers http.Header)

	// NewTrace() returns a new factory holding a new span, part of a new
	// trace.  Any span held in the invoking factory is ignored.
	//
	NewTrace() Factory

	// NewSubSpan() returns a new factory holding a new span that is a
	// sub-span of the span contained in the invoking factory.  If the
	// invoking factory was empty, then a failure with a stack trace is
	// logged and a 'nil' factory is returned.
	//
	NewSubSpan() Factory

	// NewSpan() returns a new factory holding a new span.  It does
	// NewTrace() if the factory was empty and NewSubSpan() otherwise.
	//
	NewSpan() Factory

	// Sets the span kind to "SERVER".  Does nothing except log a failure
	// with a stack trace if the factory is empty.
	//
	SetIsServer()

	// Sets the span kind to "CLIENT".  Does nothing except log a failure
	// with a stack trace if the factory is empty.
	//
	SetIsClient()

	// Sets the span kind to "PRODUCER".  Does nothing except log a failure
	// with a stack trace if the factory is empty.
	//
	SetIsPublisher()

	// Sets the span kind to "CONSUMER".  Does nothing except log a failure
	// with a stack trace if the factory is empty.
	//
	SetIsSubscriber()

	// SetDisplayName() sets the display name on the contained span.  Does
	// nothing except log a failure with a stack trace if the factory is
	// empty.
	//
	SetDisplayName(desc string)

	// AddAttribute() adds an attribute key/value pair to the contained span.
	// Does nothing except log a failure with a stack trace if the factory is
	// empty (even returning a 'nil' error).
	//
	// 'val' can be a 'string', an 'int' or 'int64', or a 'bool'.  If 'key'
	// is empty or 'val' is not one of the listed types, then an error is
	// returned and the attribute is not added.
	//
	AddAttribute(key string, val interface{}) error

	// SetStatusCode() sets the status code on the contained span.
	// 'code' is expected to be a value from
	// google.golang.org/genproto/googleapis/rpc/code but this is not
	// verified.  Does nothing except log a failure with a stack trace
	// if the factory is empty.
	//
	SetStatusCode(code int64)

	// SetStatusMessage() sets the status message string on the contained
	// span.  Does nothing except log a failure with a stack trace if the
	// factory is empty.
	//
	SetStatusMessage(msg string)

	// Finish() notifies the factory that the contained span is finished.
	// The factory will be empty afterward.  The factory will arrange for the
	// span to be registered.
	//
	// The returned value is the duration of the span's life.  If the factory
	// was already empty or the contained span was from Import(), then a
	// failure with a stack trace is logged and a 0 duration is returned.
	//
	Finish() time.Duration
}

Factory is an interface that allows Spans to be created and manipulated without depending on the GCP CloudTrace module (and its large list of dependencies).

Each factory instance can hold a single span or be empty.

func ContextGetSpan

func ContextGetSpan(ctx context.Context) Factory

type ROSpan

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

ROSpan implements Factory but only deals with Import()ed spans, thus requiring no access to GCP CloudTrace libraries. Such spans are read-only (hence "RO"), only dealing with spans created elsewhere and no changes can be made to them.

func NewROSpan

func NewROSpan(projectID string) ROSpan

NewROSpan() returns an empty Factory.

func (ROSpan) AddAttribute

func (s ROSpan) AddAttribute(_ string, _ interface{}) error

func (ROSpan) Finish

func (s ROSpan) Finish() time.Duration

func (ROSpan) GetCloudContext

func (s ROSpan) GetCloudContext() string

GetCloudContext() returns "{hex:traceID}/{decimal:spanID}" or "".

func (ROSpan) GetProjectID

func (s ROSpan) GetProjectID() string

GetProjectID() retuns the GCP Project ID.

func (ROSpan) GetSpanID

func (s ROSpan) GetSpanID() uint64

func (ROSpan) GetSpanPath

func (s ROSpan) GetSpanPath() string

GetSpanPath() returns "traces/{traceID}/spans/{spanID}" or "".

func (ROSpan) GetStart

func (s ROSpan) GetStart() time.Time

func (ROSpan) GetTraceID

func (s ROSpan) GetTraceID() string

func (ROSpan) GetTracePath

func (s ROSpan) GetTracePath() string

GetTracePath() "projects/{projectID}/traces/{traceID}" or "".

func (ROSpan) Import

func (s ROSpan) Import(traceID string, spanID uint64) (Factory, error)

Import() returns a new factory containing a span created elsewhere.

func (ROSpan) ImportFromHeaders

func (s ROSpan) ImportFromHeaders(headers http.Header) Factory

func (ROSpan) NewSpan

func (s ROSpan) NewSpan() Factory

func (ROSpan) NewSubSpan

func (s ROSpan) NewSubSpan() Factory

func (ROSpan) NewTrace

func (s ROSpan) NewTrace() Factory

func (ROSpan) SetDisplayName

func (s ROSpan) SetDisplayName(_ string)

func (ROSpan) SetHeader

func (s ROSpan) SetHeader(headers http.Header)

func (ROSpan) SetIsClient

func (s ROSpan) SetIsClient()

func (ROSpan) SetIsPublisher

func (s ROSpan) SetIsPublisher()

func (ROSpan) SetIsServer

func (s ROSpan) SetIsServer()

func (ROSpan) SetIsSubscriber

func (s ROSpan) SetIsSubscriber()

func (*ROSpan) SetSpanID

func (s *ROSpan) SetSpanID(spanID uint64)

SetSpanID() lets you set the spanID to make implementing a non-read-only span type easier. This is the only method that requires a '*ROSpan' not just a 'ROSpan'.

func (ROSpan) SetStatusCode

func (s ROSpan) SetStatusCode(_ int64)

func (ROSpan) SetStatusMessage

func (s ROSpan) SetStatusMessage(_ string)