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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Annotate ¶
Annotate is a shortcut for calling WithAnnotator using an Annotations containing the given key/value pairs.
NOTE If the length of kvs is not divisible by two this will panic.
func MergeAnnotations ¶
MergeAnnotations sequentially merges the annotation data of the passed in Contexts into the first passed in Context. 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.
func WithAnnotator ¶
WithAnnotator takes in an Annotator and returns a Context which will produce that Annotator's annotations when the Annotate function is called. The Annotator will be not be evaluated until the first call to Annotate.
Types ¶
type Annotations ¶
type Annotations map[interface{}]interface{}
Annotations is a set of key/value pairs representing a set of annotations. It implements the Annotator interface along with other useful post-processing methods.
func EvaluateAnnotations ¶
func EvaluateAnnotations(ctx context.Context, aa Annotations) Annotations
EvaluateAnnotations collects all annotation key/values which have been set via Annotate(With) on this Context and its ancestors, and sets those key/values on the given Annotations. If a key was set twice then only the most recent value is included.
For convenience the passed in Annotations is returned from this function, and if nil is given as the Annotations value then an Annotations will be allocated and returned.
func (Annotations) Annotate ¶
func (aa Annotations) Annotate(aa2 Annotations)
Annotate implements the method for the Annotator interface.
func (Annotations) StringMap ¶
func (aa Annotations) StringMap() map[string]string
StringMap formats each of the key/value pairs into strings using fmt.Sprint. If any two keys format to the same string, then type information will be prefaced to each one.
func (Annotations) StringSlice ¶
func (aa Annotations) 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.
type Annotator ¶
type Annotator interface {
Annotate(Annotations)
}
Annotator is a type which can add annotation data to an existing set of Annotations. The Annotate method should be expected to be called in a non-thread-safe manner.
func ContextAsAnnotator ¶
ContextAsAnnotator will return an Annotator which, when evaluated, will call EvaluateAnnotations on the given Context.
Source Files