Documentation
¶
Index ¶
- Constants
- Variables
- func ContextReplaceSpan(ctx context.Context, span Factory) bool
- 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
- type ROSpan
- func (s ROSpan) AddAttribute(_ string, _ interface{}) error
- func (s ROSpan) Finish() time.Duration
- func (s ROSpan) GetCloudContext() string
- func (s ROSpan) GetParent() Factory
- 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) NewChildSpan() 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 ContextReplaceSpan ¶
ContextReplaceSpan() takes a Context that should already be decorated with a span Factory [see ContextStoreSpan()]. If so, then it updates the Context in-place, replacing the Factory with the passed-in Factory, and returns 'true'. If not, it does nothing and returns 'false'.
func ContextStoreSpan ¶
ContextStoreSpan() adds a span Factory to the passed-in Context, returning the new, decorated 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 IsValidTraceID ¶
IsValidTraceID() returns 'true' only if 's' is a non-zero hexadecimal value of 32 digits.
func NonHexIndex ¶
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
// 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
// NewChildSpan() is the same as NewSpan() except that the returned (new)
// span will have a pointer to the original (parent) span that can be
// accessed via GetParent().
//
NewChildSpan() Factory
// GetParent() returns 'nil' unless it is called on a span created by
// calling NewChildSpan() on a (parent) span, in which case it returns
// that parent span.
//
GetParent() 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" (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.
//
SetIsPublisher()
// 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.
//
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 ¶
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.
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 (ROSpan) AddAttribute ¶
func (ROSpan) GetCloudContext ¶
GetCloudContext() returns "{hex:traceID}/{decimal:spanID}" or "".
func (ROSpan) GetProjectID ¶
GetProjectID() returns the GCP Project ID.
func (ROSpan) GetSpanPath ¶
GetSpanPath() returns "traces/{traceID}/spans/{spanID}" or "".
func (ROSpan) GetTraceID ¶
func (ROSpan) GetTracePath ¶
GetTracePath() "projects/{projectID}/traces/{traceID}" or "".
func (ROSpan) NewChildSpan ¶
func (ROSpan) NewSubSpan ¶
func (ROSpan) SetDisplayName ¶
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 ¶
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'.
Source Files