mctx

Documentation

Overview

Package mctx extends the builtin context package to add easy-to-use annotation functionality, which is useful for logging and errors.

All functions and methods in this package are thread-safe unless otherwise noted.

Annotations

Annotations are a special case of key/values, where the data being stored is specifically runtime metadata which would be useful for logging, error output, etc... Annotation data might include an IP address of a connected client, a userID the client has authenticated as, the primary key of a row in a database being queried, etc...

Index

• func Annotate(ctx context.Context, kvs ...interface{}) context.Context
• func Annotated(kvs ...interface{}) context.Context
• func MergeAnnotations(ctxs ...context.Context) context.Context
• func MergeAnnotationsInto(ctx context.Context, ctxs ...context.Context) context.Context
• type Annotation
• type AnnotationSet
  • func Annotations(ctx context.Context) AnnotationSet
  • func (aa AnnotationSet) StringMap() map[string]string
  • func (aa AnnotationSet) StringSlice(sorted bool) [][2]string

Functions

func Annotate

func Annotate(ctx context.Context, kvs ...interface{}) context.Context

Annotate takes in one or more key/value pairs (kvs' length must be even) and returns a Context carrying them.

func Annotated

func Annotated(kvs ...interface{}) context.Context

Annotated is a shortcut for calling Annotate with a context.Background().

func MergeAnnotations

func MergeAnnotations(ctxs ...context.Context) context.Context

MergeAnnotations sequentially merges the annotation data of the passed in Contexts into the first passed in one. Data from a Context overwrites overlapping data on all passed in Contexts to the left of it. All other aspects of the first Context remain the same, and that Context is returned with the new set of Annotation data.

NOTE this will panic if no Contexts are passed in.

func MergeAnnotationsInto

func MergeAnnotationsInto(ctx context.Context, ctxs ...context.Context) context.Context

MergeAnnotationsInto is a convenience function which works like MergeAnnotations.

Types

type Annotation

type Annotation struct {
	Key, Value interface{}
}

Annotation describes the annotation of a key/value pair made on a Context via the Annotate call.

type AnnotationSet

type AnnotationSet []Annotation

AnnotationSet describes a set of unique Annotation values which were retrieved off a Context via the Annotations function. An AnnotationSet has a couple methods on it to aid in post-processing.

func Annotations

func Annotations(ctx context.Context) AnnotationSet

Annotations returns all Annotation values which have been set via Annotate on this Context and its ancestors. If a key was set twice then only the most recent value is included.

func (AnnotationSet) StringMap

func (aa AnnotationSet) StringMap() map[string]string

StringMap formats each of the Annotations into strings using fmt.Sprint. If any two keys format to the same string, then type information will be prefaced to each one.

func (AnnotationSet) StringSlice

func (aa AnnotationSet) StringSlice(sorted bool) [][2]string

StringSlice is like StringMap but it returns a slice of key/value tuples rather than a map. If sorted is true then the slice will be sorted by key in ascending order.