xcontext

Documentation

Overview

Package xcontext implements a generic context with integrated logger, metrics, tracer and recoverer.

Index

• Variables
• func WithCancel(parent Context, errs ...error) (Context, CancelFunc)
• func WithDeadline(parent Context, t time.Time) (Context, CancelFunc)
• func WithNotify(parent Context, errs ...error) (Context, CancelFunc)
• func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
• type CancelFunc
• type Context
  • func Background() Context
  • func Extend(parent context.Context) Context
  • func NewContext(stdCtx context.Context, traceID TraceID, loggerInstance Logger, ...) Context
  • func WithResetSignalers(parent Context) Context
  • func WithStdContext(parent Context, stdCtx context.Context) Context
  • func WithValue(parent context.Context, key, value interface{}) Context
• type Fields
• type Logger
  • func LoggerFrom(stdCtx context.Context) Logger
• type Metrics
• type TimeSpan
• type TraceID
  • func NewTraceID() TraceID
  • func (traceID TraceID) String() string
• type Tracer

Variables

var (
	// DefaultLogTraceID defines if traceID should be logged by default.
	//
	// If it is disabled, then logging of traceID for a specific
	// context could be enforced this way:
	//     ctx = ctx.WithField("traceID", ctx.TraceID())
	DefaultLogTraceID = false

	// DefaultLogHostname defines if hostname should be logged by default.
	DefaultLogHostname = false

	// DefaultLogUsername defines if hostname should be logged by default.
	DefaultLogUsername = false
)

var ErrCanceled = context.Canceled

ErrCanceled is returned by Context.Err when the context was canceled

var ErrDeadlineExceeded = context.DeadlineExceeded

ErrDeadlineExceeded is returned by Context.Err when the context reached the deadline.

var ErrPaused = errors.New("job is paused")

ErrPaused is returned by Context.Err when the context was paused

Functions

func WithCancel

func WithCancel(parent Context, errs ...error) (Context, CancelFunc)

WithCancel is analog of context.WithCancel, but with support of the extended Context.

If no errs are passed, then cancel is used.

func WithDeadline

func WithDeadline(parent Context, t time.Time) (Context, CancelFunc)

WithDeadline is analog of context.WithDeadline, but with support of the extended Context..

func WithNotify

func WithNotify(parent Context, errs ...error) (Context, CancelFunc)

WithNotify is analog WithCancel, but does a notification signal instead (which does not close the context).

Panics if no errs are passed.

func WithTimeout

func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)

WithTimeout is analog of context.WithTimeout, but with support of the extended Context.

Types

type CancelFunc

type CancelFunc = context.CancelFunc

type Context

type Context interface {
	context.Context
	logger.MinimalLogger

	// Clone just returns a copy of the Context safe to be modified.
	Clone() Context

	// TraceID returns the TraceID attached to the Context
	TraceID() TraceID

	// WithTraceID returns a clone of the Context, but with passed TraceID.
	WithTraceID(TraceID) Context

	// Logger returns the Logger handler attached to the Context
	Logger() Logger

	// WithLogger returns a clone of the Context, but with passed Logger handler.
	WithLogger(logger Logger) Context

	// Metrics returns the Metrics handler attached to the Context.
	Metrics() Metrics

	// WithMetrics returns a clone of the Context, but with passed Metrics handler.
	WithMetrics(Metrics) Context

	// Tracer returns the Tracer handler attached to the Context.
	Tracer() Tracer

	// WithTracer returns a clone of the Context, but with passed Tracer handler.
	WithTracer(Tracer) Context

	// WithTag returns a clone of the context, but with added tag with key
	// "key" and value "value".
	//
	// Note about Tag vs Field: Tag is supposed to be used for limited amount
	// of values, while Field is supposed to be used for arbitrary values.
	// Basically currentTags are used for everything (Logger, Metrics and Tracer),
	// while Fields are used only for Logger and Tracer.
	// We cannot use arbitrary values for Metrics because it will create
	// "infinite" amount of metrics.
	WithTag(key string, value interface{}) Context

	// WithTags returns a clone of the context, but with added tags with
	// key and values according to map "Fields".
	//
	// See also WithTag.
	WithTags(Fields) Context

	// WithField returns a clone of the context, but with added field with key
	// "key" and value "value".
	//
	// See also WithTag.
	WithField(key string, value interface{}) Context

	// WithFields returns a clone of the context, but with added fields with
	// key and values according to map "Fields".
	//
	// See also WithTag.
	WithFields(Fields) Context

	// Until works similar to Done(), but it is possible to specify specific
	// signal to wait for.
	//
	// If err is nil, then waits for any event.
	Until(err error) <-chan struct{}

	// StdCtxUntil is the same as Until, but returns a standard context
	// instead of a channel.
	StdCtxUntil(err error) context.Context

	// IsSignaledWith returns true if the context received a cancel
	// or a notification signal equals to any of passed ones.
	//
	// If errs is empty, then returns true if the context received any
	// cancel or notification signal.
	IsSignaledWith(errs ...error) bool

	// Notifications returns all the received notifications (including events
	// received by parents).
	//
	// This is a read-only value, do not modify it.
	Notifications() []error

	// Recover is use instead of standard "recover()" to also log the panic.
	Recover() interface{}
	// contains filtered or unexported methods
}

Context is a generic extension over context.Context with provides also: * Logger which allows to send messages to a log. * Metrics which allows to update metrics. * Tracer which allows to log time spans (to profile delays of the application). * TraceID to track across multiple processes.

func Background

func Background() Context

Background is analog of standard context.Context which returns just a simple dummy context which does nothing.

func Extend

func Extend(parent context.Context) Context

Extend converts a standard context to an extended one

func NewContext

func NewContext(
	stdCtx context.Context,
	traceID TraceID,
	loggerInstance Logger,
	metrics Metrics,
	tracer Tracer,
	tags Fields,
	fields Fields,
) Context

NewContext is a customizable constructor of a context.

It is not intended to be called by an user not familiar with this package, there are special helpers for that, see for example bundles.NewContextWithLogrus.

func WithResetSignalers

func WithResetSignalers(parent Context) Context

WithResetSignalers resets all signalers (cancelers and notifiers).

func WithStdContext

func WithStdContext(parent Context, stdCtx context.Context) Context

WithStdContext adds events and values of a standard context.

func WithValue

func WithValue(parent context.Context, key, value interface{}) Context

WithValue is analog of of context.WithValue but for extended context.

type Fields

type Fields = fields.Fields

Fields is a multiple of fields which are attached to logger/tracer messages.

type Logger

type Logger = logger.Logger

Logger is an abstract logger used by a Context.

func LoggerFrom

func LoggerFrom(stdCtx context.Context) Logger

LoggerFrom returns a logger from a context.Context if can find any. And returns a dummy logger (which does nothing) if wasn't able to find any.

type Metrics

type Metrics = metrics.Metrics

Metrics is a handler of metrics (like Prometheus, ODS)

type TimeSpan

type TimeSpan interface {
	// Finish sets the end time of the span to time.Now() and sends
	// the time span to the log of the Tracer.
	Finish() time.Duration
}

TimeSpan is the object represents the time span to be reported by a Tracer.

type TraceID

type TraceID string

TraceID is a passthrough ID used to track a sequence of events across multiple processes/services. It is supposed to pass it with Thrift-requests through a HTTP-header "X-Trace-Id".

func NewTraceID

func NewTraceID() TraceID

NewTraceID returns a new random unique TraceID.

func (TraceID) String

func (traceID TraceID) String() string

String implements fmt.Stringer.

type Tracer

type Tracer interface {
	// StartSpan creates a time span to be reported (if Finish will be called)
	// which starts counting time since the moment StartSpan was called.
	StartSpan(label string) TimeSpan

	// WithField returns a Tracer with an added field to be reported with the time span (when Finish will be called).
	WithField(key string, value interface{}) Tracer

	// WithField returns a Tracer with added fields to be reported with the time span (when Finish will be called).
	WithFields(Fields) Tracer
}

Tracer is a handler responsible to track time spans.

Is supposed to be used this way:

defer ctx.Tracer().StartSpan("some label here").Finish()