trace

Documentation

Overview

This module makes it easy to register a Span (and associated Trace) in GCP (Google Cloud Platform) CloudTrace (API v2).

References to "ct2." refer to items imported from the "google.golang.org/api/cloudtrace/v2" module. References to "lager." refer to items imported from "github.com/TyeMcQueen/go-lager". "spans." refers to "github.com/TyeMcQueen/go-lager/gcp-spans".

Index

• Constants
• func ContextPushSpan(pCtx *context.Context, name string) spans.Factory
• func NewSpanID(oldSpanID uint64) (spanID uint64)
• func NewTraceID(oldTraceID string) string
• func StartServer(pCtx *context.Context, runners int, pRegs ...**Registrar) func()
• func TimeAsString(when time.Time) string
• type Client
  • func MustNewClient(ctx context.Context, svc *ct2.Service) Client
  • func NewClient(ctx context.Context, svc *ct2.Service) (Client, error)
• type Registrar
  • func MustNewRegistrar(project string, client Client, runners int) *Registrar
  • func NewRegistrar(project string, client Client, runners int) (*Registrar, error)
  • func (r *Registrar) Halt()
  • func (r *Registrar) NewFactory() spans.Factory
  • func (r *Registrar) WaitForIdleRunners()
• type Span
  • func (s *Span) AddAttribute(key string, val interface{}) error
  • func (s *Span) AddPairs(pairs ...interface{}) spans.Factory
  • func (s *Span) Finish() time.Duration
  • func (s Span) GetParent() spans.Factory
  • func (s Span) GetStart() time.Time
  • func (s Span) Import(traceID string, spanID uint64) (spans.Factory, error)
  • func (s Span) ImportFromHeaders(headers http.Header) spans.Factory
  • func (s Span) NewSpan() spans.Factory
  • func (s *Span) NewSubSpan() spans.Factory
  • func (s Span) NewTrace() spans.Factory
  • func (s *Span) SetDisplayName(desc string) spans.Factory
  • func (s *Span) SetIsClient() spans.Factory
  • func (s *Span) SetIsPublisher() spans.Factory
  • func (s *Span) SetIsServer() spans.Factory
  • func (s *Span) SetIsSubscriber() spans.Factory
  • func (s *Span) SetStatusCode(code int64) spans.Factory
  • func (s *Span) SetStatusMessage(msg string) spans.Factory

Constants

const ZuluTime = "2006-01-02T15:04:05.999999Z"

Functions

func ContextPushSpan

func ContextPushSpan(pCtx *context.Context, name string) spans.Factory

ContextPushSpan() takes a pointer to a Context which should already be decorated with a span Factory [see spans.ContextStoreSpan()]. If so, it calls NewSubSpan() on that span, replaces the Context with a copy that is decorated with the new child span, and returns the child span.

If not, it logs the lack of a span in the Context (including a stack trace) and returns an empty read-only span that is mostly useless other than not being 'nil'.

It can be used like:

defer trace.ContextPushSpan(&ctx, "span.name").AddPairs(
    "user", user,
).Finish()

func NewSpanID

func NewSpanID(oldSpanID uint64) (spanID uint64)

NewSpanID() just generates a random uint64 value. You are never expected to call this directly. It prefers to use cryptographically strong random values but will resort to math/rand.Uint64() if that fails. Such a failure will be logged via lager.Warn() only once but the attempt is always made.

func NewTraceID

func NewTraceID(oldTraceID string) string

NewTraceID() returns a new trace ID that can be used with GCP CloudTrace. It is just a randomly generated sequence of 32 hexadecimal digits. You are not expected to call this directly.

If 'oldTraceID' is a valid trace ID, then it is used to add more randomness to the new trace ID (and can't return that same trace ID).

func StartServer

func StartServer(
	pCtx *context.Context, runners int, pRegs ...**Registrar,
) func()

StartServer() is the simplest start-up code to include in a server to enable GCP-based tracing, usually called like:

ctx := context.Background()
defer trace.StartServer(&ctx, 1)()
// Have 'ctx' returned by the http.Server.BaseContext func.

This assumes that the calling function will not exit until the server is shutting down.

You can also add an extra argument that is a pointer to a variable of type '*Registrar' to have that variable set to the span Registrar (mostly useful when testing).

func TimeAsString

func TimeAsString(when time.Time) string

Types

type Client

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

See NewClient().

func MustNewClient

func MustNewClient(ctx context.Context, svc *ct2.Service) Client

MustNewClient() calls NewClient(). If that fails, then lager.Exit() is used to log the error and abort the process.

func NewClient

func NewClient(ctx context.Context, svc *ct2.Service) (Client, error)

NewClient() creates a new client capable of registering Spans in the GCP CloudTrace API v2. This client has no methods but should be passed in when starting the Registrar.

To get a default connection, pass in 'nil' for 'svc'. Otherwise you can use ct2.NewService() or ct2.New() to create a base service to use and pass the result in as 'svc'.

If 'svc' is 'nil', then 'ctx' is the Context used when creating the base service using default options. If 'svc' is not 'nil', then 'ctx' is ignored.

type Registrar

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

Registrar is mostly just an object to use to Halt() the registration runners that got started when you created the Registrar.

It also can create an empty spans.Factory that can be used to create and manipulate spans.

func MustNewRegistrar

func MustNewRegistrar(
	project string, client Client, runners int,
) *Registrar

MustNewRegistrar() calls NewRegistrar() and, if that fails, uses lager.Exit() to abort the process.

func NewRegistrar

func NewRegistrar(
	project string, client Client, runners int,
) (*Registrar, error)

NewRegistrar() starts a number of go-routines (given by 'runners') that wait to receive Finish()ed Spans and then register them with GCP Cloud Trace.

func (*Registrar) Halt

func (r *Registrar) Halt()

Halt() tells the runners to terminate and waits for them all to finish before returning.

Halt() should only be called after you are sure that no more spans will be Finish()ed. Any spans Finish()ed after Halt() has been called may cause a panic(). Not waiting for Halt() to return can mean that recently Finish()ed spans might not be registered.

func (*Registrar) NewFactory

func (r *Registrar) NewFactory() spans.Factory

NewFactory() returns a spans.Factory that can be used to create and manipulate spans and eventually register them with GCP Cloud Trace.

func (*Registrar) WaitForIdleRunners

func (r *Registrar) WaitForIdleRunners()

WaitForIdleRunners() is only meant to be used by tests. It allows you to ensure that all prior Finish()ed Spans have been processed so the test can check for any errors that were logged.

It works by sending one request per runner that will cause that runner to wait when it receives it. Then it reads the responses from all of the runners (which ends their waiting) and then returns.

type Span

type Span struct {
	spans.ROSpan
	// contains filtered or unexported fields
}

Span tracks a span inside of a trace and can be used to create new child spans within it. It also registers the span with GCP when Finish() is called on it [unless it was created via Import()].

A Span object is expected to be modified only from a single goroutine and so no locking is implemented. Creation of sub-spans does implement locking so that multiple go routines can safely create sub-spans from the same span without additional locking.

func (*Span) AddAttribute

func (s *Span) AddAttribute(key string, val interface{}) error

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 or Import()ed (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.

func (*Span) AddPairs

func (s *Span) AddPairs(pairs ...interface{}) spans.Factory

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.

Does nothing except log a single failure with a stack trace if the factory is empty or Import()ed.

func (*Span) Finish

func (s *Span) Finish() time.Duration

Finish() notifies the factory that the contained span is finished. The factory will be read-only (as if 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 Import()ed, then a failure with a stack trace is logged and a 0 duration is returned.

func (Span) GetParent

func (s Span) GetParent() spans.Factory

GetParent() returns 'nil' unless it is called on a span created by calling NewSubSpan() [or NewSpan()] on a parent span (in which case it returns that parent span).

func (Span) GetStart

func (s Span) GetStart() time.Time

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.

func (Span) Import

func (s Span) Import(traceID string, spanID uint64) (spans.Factory, error)

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

func (Span) ImportFromHeaders

func (s Span) ImportFromHeaders(headers http.Header) spans.Factory

func (Span) NewSpan

func (s Span) NewSpan() spans.Factory

NewSpan() returns a new factory holding a new span; either NewTrace() or NewSubSpan(), depending on whether the invoking factory is empty.

func (*Span) NewSubSpan

func (s *Span) NewSubSpan() spans.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() locks the calling span so that you can safely call NewSubSpan() on the same parent span from multiple go routines.

func (Span) NewTrace

func (s Span) NewTrace() spans.Factory

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

func (*Span) SetDisplayName

func (s *Span) SetDisplayName(desc string) spans.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 or Import()ed.

func (*Span) SetIsClient

func (s *Span) SetIsClient() spans.Factory

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

func (*Span) SetIsPublisher

func (s *Span) SetIsPublisher() spans.Factory

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

func (*Span) SetIsServer

func (s *Span) SetIsServer() spans.Factory

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

func (*Span) SetIsSubscriber

func (s *Span) SetIsSubscriber() spans.Factory

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

func (*Span) SetStatusCode

func (s *Span) SetStatusCode(code int64) spans.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.

func (*Span) SetStatusMessage

func (s *Span) SetStatusMessage(msg string) spans.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.