trace

Documentation

Overview

Package trace contains a helper interface that allows various tracing tools to be plugged in to components using this interface. If no plugin is registered, the default one makes all trace calls into no-ops.

Index

• func AddGrpcClientOptions(...)
• func AddGrpcServerOptions(...)
• func AnnotateSQL(span Span, strippedSQL fmt.Stringer)
• func CopySpan(parentCtx, spanCtx context.Context) context.Context
• func LogErrorsWhenClosing(in io.Closer) func()
• func NewContext(parent context.Context, span Span) context.Context
• func RegisterFlags(fs *pflag.FlagSet)
• func StartTracing(serviceName string) io.Closer
• type NoopSpan
  • func (NoopSpan) Annotate(string, any)
  • func (NoopSpan) Finish()
• type Span
  • func FromContext(ctx context.Context) (Span, bool)
  • func NewFromString(inCtx context.Context, parent, label string) (Span, context.Context, error)
  • func NewSpan(inCtx context.Context, label string) (Span, context.Context)
• type TracerFactory

Functions

func AddGrpcClientOptions

func AddGrpcClientOptions(addInterceptors func(s grpc.StreamClientInterceptor, u grpc.UnaryClientInterceptor))

AddGrpcClientOptions adds GRPC interceptors that add parent information to outgoing grpc packets

func AddGrpcServerOptions

func AddGrpcServerOptions(addInterceptors func(s grpc.StreamServerInterceptor, u grpc.UnaryServerInterceptor))

AddGrpcServerOptions adds GRPC interceptors that read the parent span from the grpc packets

func AnnotateSQL

func AnnotateSQL(span Span, strippedSQL fmt.Stringer)

AnnotateSQL annotates information about a sql query in the span. This is done in a way so as to not leak personally identifying information (PII), or sensitive personal information (SPI)

func CopySpan

func CopySpan(parentCtx, spanCtx context.Context) context.Context

CopySpan creates a new context from parentCtx, with only the trace span copied over from spanCtx, if it has any. If not, parentCtx is returned.

func LogErrorsWhenClosing

func LogErrorsWhenClosing(in io.Closer) func()

LogErrorsWhenClosing will close the provided Closer, and log any errors it generates

func NewContext

func NewContext(parent context.Context, span Span) context.Context

NewContext returns a context based on parent with a new Span value.

func RegisterFlags

func RegisterFlags(fs *pflag.FlagSet)

func StartTracing

func StartTracing(serviceName string) io.Closer

StartTracing enables tracing for a named service

Types

type NoopSpan

type NoopSpan struct{}

NoopSpan implements Span with no-op methods.

func (NoopSpan) Annotate

func (NoopSpan) Annotate(string, any)

func (NoopSpan) Finish

func (NoopSpan) Finish()

type Span

type Span interface {
	Finish()
	// Annotate records a key/value pair associated with a Span. It should be
	// called between Start and Finish.
	Annotate(key string, value any)
}

Span represents a unit of work within a trace. After creating a Span with NewSpan(), call one of the Start methods to mark the beginning of the work represented by this Span. Call Finish() when that work is done to record the Span. A Span may be reused by calling Start again.

func FromContext

func FromContext(ctx context.Context) (Span, bool)

FromContext returns the Span from a Context if present. The bool return value indicates whether a Span was present in the Context.

func NewFromString

func NewFromString(inCtx context.Context, parent, label string) (Span, context.Context, error)

NewFromString creates a new Span with the currently installed tracing plugin, extracting the span context from the provided string.

func NewSpan

func NewSpan(inCtx context.Context, label string) (Span, context.Context)

NewSpan creates a new Span with the currently installed tracing plugin. If no tracing plugin is installed, it returns a fake Span that does nothing.

type TracerFactory

type TracerFactory func(serviceName string) (tracingService, io.Closer, error)

TracerFactory creates a tracing service for the service provided. It's important to close the provided io.Closer object to make sure that all spans are sent to the backend before the process exits.