spans

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Feb 23, 2023 License: Unlicense Imports: 6 Imported by: 1

Documentation

Overview

This package is still in beta and the public interface may undergo changes without a full deprecation cycle.

Index

Constants

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

Variables

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

ContextStoreSpan() adds a span Factory to the passed-in Context, returning the new, decorated Context.

func FinishSpan 

func FinishSpan(span Factory) time.Duration

FinishSpan() calls Finish() on the passed-in 'span', unless it is 'nil'. It is most useful 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() returns the GCP Project ID (which is not the Project
	// Number) for which spans will be registered.
	//
	GetProjectID() string

	// GetTraceID() returns "" 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() returns 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

	// GetDuration() returns a negative duration if the factory is empty or
	// if the span has not been Finish()ed yet.  Otherwise, it returns the
	// span's duration.
	//
	GetDuration() time.Duration

	// 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.  Always returns the calling Factory so that further
	// method calls can be chained.
	//
	SetHeader(headers http.Header) Factory

	// 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.  Always returns the calling
	// Factory so further method calls can be chained.
	//
	SetIsServer() Factory

	// Sets the span kind to "CLIENT".  Does nothing except log a failure
	// with a stack trace if the Factory is empty.  Always returns the
	// calling Factory so further method calls can be chained.
	//
	SetIsClient() Factory

	// Sets the span kind to "PRODUCER" (the term used for a process that
	// asynchronously publishes data like with pub/sub).  Does nothing
	// except log a failure with a stack trace if the Factory is empty.
	// Always returns the calling Factory so further method calls can be
	// chained.
	//
	SetIsPublisher() Factory

	// Sets the span kind to "CONSUMER" (the term used for a process that
	// asynchronously receives data like a pub/sub subscriber).  Does nothing
	// except log a failure with a stack trace if the Factory is empty.
	// Always returns the calling Factory so further method calls can be
	// chained.
	//
	SetIsSubscriber() Factory

	// SetDisplayName() sets the display name on the contained span.  Does
	// nothing except log a failure with a stack trace if the Factory is
	// empty.  Always returns the calling Factory so further method calls
	// can be chained.
	//
	SetDisplayName(desc string) Factory

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

	// AddPairs() takes a list of attribute key/value pairs.  For each pair,
	// AddAttribute() is called and any returned error is logged (including
	// a reference to the line of code that called AddPairs).  Always returns
	// the calling Factory so further method calls can be chained.
	//
	AddPairs(pairs ...interface{}) Factory

	// 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.  HTTP status codes are also understood by the library.
	// Does nothing except log a failure with a stack trace if the Factory
	// is empty.  Always returns the calling span so further method calls
	// can be chained.
	//
	SetStatusCode(code int64) Factory

	// SetStatusMessage() sets the status message string on the contained
	// span.  By convention, only a failure should set a status message.
	// Does nothing except log a failure with a stack trace if the Factory
	// is empty.  Always returns the calling Factory so further method calls
	// can be chained.
	//
	SetStatusMessage(msg string) Factory

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

ContextGetSpan() extracts a span Factory from the passed-in Context and returns it (or 'nil').

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.

The only non-trivial methods for ROSpan are Import() and ImportFromHeader() and then, on such imported spans: GetSpanID(), GetTraceID(), GetTracePath(), GetSpanPath(), GetCloudContext(), and SetHeader().

NewSubSpan() always returns 'nil'. The other New*() methods always return an empty span. Methods that should log when called on an empty span also do not log for ROSpans since those methods do nothing even if the span is not empty.

func NewROSpan 

func NewROSpan(projectID string) ROSpan

NewROSpan() returns an empty Factory.

func (ROSpan) AddAttribute 

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

func (ROSpan) AddPairs added in v1.2.3 

func (s ROSpan) AddPairs(_ ...interface{}) Factory

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) GetDuration added in v1.2.3 

func (s ROSpan) GetDuration() time.Duration

func (ROSpan) GetProjectID 

func (s ROSpan) GetProjectID() string

GetProjectID() returns 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) Factory

func (ROSpan) SetHeader 

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

func (ROSpan) SetIsClient 

func (s ROSpan) SetIsClient() Factory

func (ROSpan) SetIsPublisher 

func (s ROSpan) SetIsPublisher() Factory

func (ROSpan) SetIsServer 

func (s ROSpan) SetIsServer() Factory

func (ROSpan) SetIsSubscriber 

func (s ROSpan) SetIsSubscriber() Factory

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

func (ROSpan) SetStatusMessage 

func (s ROSpan) SetStatusMessage(_ string) Factory

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.