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

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.