spcontext

README

spcontext: standard context on steroids

Includes:

• logging;
• exception tracking;
• APM;

Documentation

Index

• Constants
• func ContextInjector(ctx *Context) func(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)
• func GRPCStreamContextInjector(ctx *Context) grpc.StreamServerInterceptor
• func WithCancel(ctx *Context) (*Context, CancelFunc)
• type BugsnagLogger
  • func (l *BugsnagLogger) Printf(format string, v ...interface{})
• type CancelFunc
• type Context
  • func BackgroundFrom(ctx *Context) *Context
  • func BackgroundWithValuesFrom(ctx *Context) *Context
  • func FromStdContext(stdCtx context.Context) *Context
  • func New(logger Logger, opts ...ContextOption) *Context
  • func WithDeadline(ctx *Context, d time.Time) (*Context, context.CancelFunc)
  • func WithDeadlineCause(ctx *Context, d time.Time, cause error) (*Context, context.CancelFunc)
  • func WithTimeout(ctx *Context, timeout time.Duration) (*Context, context.CancelFunc)
  • func WithTimeoutCause(ctx *Context, timeout time.Duration, cause error) (*Context, context.CancelFunc)
  • func WithValue(ctx *Context, key, val interface{}) *Context
  • func (ctx *Context) Debugf(format string, args ...interface{})
  • func (ctx *Context) DirectError(err error, message string) error
  • func (ctx *Context) Error(err error, internal InternalMessage, safe SafeMessage) error
  • func (ctx *Context) Errorf(format string, args ...interface{})
  • func (ctx *Context) EvaluateBugsnagMetadata() bugsnag.MetaData
  • func (ctx *Context) Fields() *Fields
  • func (ctx *Context) Infof(format string, args ...interface{})
  • func (ctx *Context) InternalError(err error, message string) error
  • func (ctx *Context) RawError(err error, message string) error
  • func (ctx *Context) StartSpan(opts ...SpanOption) (*Context, Span)
  • func (ctx *Context) Value(key interface{}) interface{}
  • func (ctx *Context) Warnf(format string, args ...interface{})
  • func (ctx *Context) With(kvs ...interface{}) *Context
• type ContextOption
  • func OnSpanStart(hook func(parentSpan, activeSpan Span)) ContextOption
  • func WithNotifier(notifier Notifier) ContextOption
  • func WithTracer(tracer Tracer) ContextOption
• type Fields
  • func (fields *Fields) Append(newFields *Fields) *Fields
  • func (fields *Fields) EvaluateFields() []interface{}
  • func (fields *Fields) Value(key string) interface{}
  • func (fields *Fields) With(kvs ...interface{}) *Fields
• type IgnoreLogError
  • func (i IgnoreLogError) Log(args ...interface{})
• type InternalMessage
• type Logger
• type NopTracer
  • func (n *NopTracer) GetLogFields(ctx *Context) []interface{}
  • func (n *NopTracer) OnSpanClose(ctx *Context, err error, fields []interface{}, drop, analyze bool)
  • func (n *NopTracer) OnSpanStart(ctx *Context, name, resource string) *Context
• type Notifier
• type SafeMessage
• type Span
• type SpanCloseConfig
• type SpanCloseOption
  • func WithAnalyze() SpanCloseOption
  • func WithDrop() SpanCloseOption
• type SpanConfig
• type SpanOption
  • func WithOperation(operation string, a ...interface{}) SpanOption
  • func WithResource(resource string, a ...interface{}) SpanOption
  • func WithTags(tags ...interface{}) SpanOption
• type Tracer
• type Valuer

Constants

const FieldsTab = "fields"

FieldsTab is the tab in bugsnag to put metadata fields into.

Functions

func ContextInjector

func ContextInjector(ctx *Context) func(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)

ContextInjector injects the given context into each request. Swapping the underlying context.Context for the one in the request.

func GRPCStreamContextInjector

func GRPCStreamContextInjector(ctx *Context) grpc.StreamServerInterceptor

GRPCStreamContextInjector injects the given context into each stream. Swapping the underlying context.Context for the one in the request.

func WithCancel

func WithCancel(ctx *Context) (*Context, CancelFunc)

WithCancel returns a cancelable context. Use instead of context.WithCancel

Types

type BugsnagLogger

type BugsnagLogger struct {
	Ctx Context
}

BugsnagLogger wraps the given Context inside a bugsnag friendly logger.

func (*BugsnagLogger) Printf

func (l *BugsnagLogger) Printf(format string, v ...interface{})

Printf logs the message with info level.

type CancelFunc

type CancelFunc = context.CancelFunc

CancelFunc is a function you can call to cancel the connected context.

type Context

type Context struct {
	context.Context

	Notifier Notifier

	Tracer Tracer
	// contains filtered or unexported fields
}

Context is a drop-in replacement to context.Context. Include logging, error reporting and structured metadata.

func BackgroundFrom

func BackgroundFrom(ctx *Context) *Context

BackgroundFrom creates a new context.Background() from the given Context. This keeps all metadata fields and the logger/notifier configuration. Use instead of context.Background().

func BackgroundWithValuesFrom

func BackgroundWithValuesFrom(ctx *Context) *Context

BackgroundWithValuesFrom creates a new background context from the given Context. This keeps all key-values, metadata fields and the logger/notifier configuration. Use instead of BackgroundFrom when you want to keep key-value information.

func FromStdContext

func FromStdContext(stdCtx context.Context) *Context

FromStdContext tries to find a spcontext.Context inside the given context.Context and returns a new one based on it. If no spcontext.Context is found, a default noop Context is returned.

func New

func New(logger Logger, opts ...ContextOption) *Context

New creates a new context with the logger and configured using additional options.

func WithDeadline

func WithDeadline(ctx *Context, d time.Time) (*Context, context.CancelFunc)

WithDeadline returns a context with a deadline. Use instead of context.WithDeadline.

func WithDeadlineCause

func WithDeadlineCause(ctx *Context, d time.Time, cause error) (*Context, context.CancelFunc)

WithDeadlineCause returns a context with a deadline, but also sets the cause of the returned Context when the deadline is exceeded. The returned CancelFunc does not set the cause. Use instead of context.WithDeadlineCause.

func WithTimeout

func WithTimeout(ctx *Context, timeout time.Duration) (*Context, context.CancelFunc)

WithTimeout returns a context with a timeout. Use instead of context.WithTimeout.

func WithTimeoutCause

func WithTimeoutCause(ctx *Context, timeout time.Duration, cause error) (*Context, context.CancelFunc)

WithTimeoutCause returns a context with a timeout, but also sets the cause of the returned Context when the timeout expires. The returned CancelFunc does not set the cause. Use instead of context.WithTimeoutCause.

func WithValue

func WithValue(ctx *Context, key, val interface{}) *Context

WithValue adds a key value to the context. Use instead of context.WithValue

func (*Context) Debugf

func (ctx *Context) Debugf(format string, args ...interface{})

Debugf logs the message with debug level.

func (*Context) DirectError

func (ctx *Context) DirectError(err error, message string) error

DirectError directly notifies about the error, without caring which error is user-facing, and which isn't.

func (*Context) Error

func (ctx *Context) Error(err error, internal InternalMessage, safe SafeMessage) error

Error reports the error to the logger and Bugsnag, while returning an error with a user-safe message.

func (*Context) Errorf

func (ctx *Context) Errorf(format string, args ...interface{})

Errorf logs the message with error level.

func (*Context) EvaluateBugsnagMetadata

func (ctx *Context) EvaluateBugsnagMetadata() bugsnag.MetaData

EvaluateBugsnagMetadata returns Bugsnag metadata with the evaluated fields.

func (*Context) Fields

func (ctx *Context) Fields() *Fields

Fields returns the context fields.

func (*Context) Infof

func (ctx *Context) Infof(format string, args ...interface{})

Infof logs the message with info level.

func (*Context) InternalError

func (ctx *Context) InternalError(err error, message string) error

InternalError reports an error with a generic user-facing message.

func (*Context) RawError

func (ctx *Context) RawError(err error, message string) error

RawError reports an error wrapped in a message.

func (*Context) StartSpan

func (ctx *Context) StartSpan(opts ...SpanOption) (*Context, Span)

StartSpan starts a new span using the context fields as metadata. It returns a new context with attached trace and span IDs as metadata.

func (*Context) Value

func (ctx *Context) Value(key interface{}) interface{}

Value returns the value for the given key in this context stack.

func (*Context) Warnf

func (ctx *Context) Warnf(format string, args ...interface{})

Warnf logs the message with warning level.

func (*Context) With

func (ctx *Context) With(kvs ...interface{}) *Context

With adds the given alternating keys and values to the context, returning a new child context.

type ContextOption

type ContextOption func(ctx *Context)

ContextOption is used to optionally configure the context on creation.

func OnSpanStart

func OnSpanStart(hook func(parentSpan, activeSpan Span)) ContextOption

OnSpanStart adds an on span start hook to the new context.

func WithNotifier

func WithNotifier(notifier Notifier) ContextOption

WithNotifier adds an optional notifier to the new context.

func WithTracer

func WithTracer(tracer Tracer) ContextOption

WithTracer adds an optional tracer to the new context.

type Fields

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

Fields represents and contains structure metadata.

func (*Fields) Append

func (fields *Fields) Append(newFields *Fields) *Fields

Append appends new Fields to the current ones, modifying the argument.

func (*Fields) EvaluateFields

func (fields *Fields) EvaluateFields() []interface{}

EvaluateFields returns the fields as keys and evaluated values.

func (*Fields) Value

func (fields *Fields) Value(key string) interface{}

Value returns the value for the given key or nil if it's not available.

func (*Fields) With

func (fields *Fields) With(kvs ...interface{}) *Fields

With creates a new child Fields with additional fields. Panics if odd number of arguments were passed or key(first value of each pair) is not a string.

type IgnoreLogError

type IgnoreLogError func(...interface{}) error

IgnoreLogError wraps a logging function that returns an error and provides one that does not.

func (IgnoreLogError) Log

func (i IgnoreLogError) Log(args ...interface{})

Log suppresses the error from the underlying logging function.

type InternalMessage

type InternalMessage error

InternalMessage is an internal error message not meant for users.

type Logger

type Logger interface {
	Log(keyvals ...interface{}) error
}

Logger models the accepted logger underlying the context.

type NopTracer

type NopTracer struct {
}

NopTracer is a Tracer which does nothing.

func (*NopTracer) GetLogFields

func (n *NopTracer) GetLogFields(ctx *Context) []interface{}

GetLogFields does nothing.

func (*NopTracer) OnSpanClose

func (n *NopTracer) OnSpanClose(ctx *Context, err error, fields []interface{}, drop, analyze bool)

OnSpanClose does nothing.

func (*NopTracer) OnSpanStart

func (n *NopTracer) OnSpanStart(ctx *Context, name, resource string) *Context

OnSpanStart does nothing.

type Notifier

type Notifier interface {
	Notify(error, ...interface{}) error
	AutoNotify(...interface{})
}

Notifier models the bugsnag interface.

type SafeMessage

type SafeMessage error

SafeMessage is a safe, user-friendly error message.

type Span

type Span interface {
	Analyze()
	Close(err error, opts ...SpanCloseOption)
	Drop()
	SetTags(tags ...interface{})
}

Span is a single tracing span, which can be closed with the given error.

type SpanCloseConfig

type SpanCloseConfig struct {
	Drop, Analyze bool
}

SpanCloseConfig configures Span finalization.

type SpanCloseOption

type SpanCloseOption func(*SpanCloseConfig)

SpanCloseOption is used to modify the SpanCloseConfig.

func WithAnalyze

func WithAnalyze() SpanCloseOption

WithAnalyze sets the Span to be analyzed.

func WithDrop

func WithDrop() SpanCloseOption

WithDrop sets the Span to be dropped.

type SpanConfig

type SpanConfig struct {
	Tags      *Fields
	Operation string
	Resource  string
}

SpanConfig configures Span creation.

type SpanOption

type SpanOption func(*SpanConfig)

SpanOption is used to modify the SpanConfig.

func WithOperation

func WithOperation(operation string, a ...interface{}) SpanOption

WithOperation sets an operation name on the Span. The name will be trimmed to allowed characters only.

func WithResource

func WithResource(resource string, a ...interface{}) SpanOption

WithResource sets the resource name on the span.

func WithTags

func WithTags(tags ...interface{}) SpanOption

WithTags adds the tags to the Span.

type Tracer

type Tracer interface {
	OnSpanStart(ctx *Context, name, resource string) *Context
	OnSpanClose(ctx *Context, err error, fields []interface{}, drop, analyze bool)
	GetLogFields(ctx *Context) []interface{}
}

Tracer is used to create spans.

type Valuer

type Valuer log.Valuer

Valuer can be passed to get dynamic values in log fields.