context

Documentation

Overview

Package context provides several utilities for working with golang.org/x/net/context in http requests. Primarily, the focus is on logging relevant request information but this package is not limited to that purpose.

The easiest way to get started is to get the background context:

ctx := context.Background()

The returned context should be passed around your application and be the root of all other context instances. If the application has a version, this line should be called before anything else:

ctx := context.WithVersion(context.Background(), version)

The above will store the version in the context and will be available to the logger.

Logging

The most useful aspect of this package is GetLogger. This function takes any context.Context interface and returns the current logger from the context. Canonical usage looks like this:

GetLogger(ctx).Infof("something interesting happened")

GetLogger also takes optional key arguments. The keys will be looked up in the context and reported with the logger. The following example would return a logger that prints the version with each log message:

ctx := context.Context(context.Background(), "version", version)
GetLogger(ctx, "version").Infof("this log message has a version field")

The above would print out a log message like this:

INFO[0000] this log message has a version field        version=v2.0.0-alpha.2.m

When used with WithLogger, we gain the ability to decorate the context with loggers that have information from disparate parts of the call stack. Following from the version example, we can build a new context with the configured logger such that we always print the version field:

ctx = WithLogger(ctx, GetLogger(ctx, "version"))

Since the logger has been pushed to the context, we can now get the version field for free with our log messages. Future calls to GetLogger on the new context will have the version field:

GetLogger(ctx).Infof("this log message has a version field")

This becomes more powerful when we start stacking loggers. Let's say we have the version logger from above but also want a request id. Using the context above, in our request scoped function, we place another logger in the context:

ctx = context.WithValue(ctx, "http.request.id", "unique id") // called when building request context
ctx = WithLogger(ctx, GetLogger(ctx, "http.request.id"))

When GetLogger is called on the new context, "http.request.id" will be included as a logger field, along with the original "version" field:

INFO[0000] this log message has a version field        http.request.id=unique id version=v2.0.0-alpha.2.m

Note that this only affects the new context, the previous context, with the version field, can be used independently. Put another way, the new logger, added to the request context, is unique to that context and can have request scoped varaibles.

HTTP Requests

This package also contains several methods for working with http requests. The concepts are very similar to those described above. We simply place the request in the context using WithRequest. This makes the request variables available. GetRequestLogger can then be called to get request specific variables in a log line:

ctx = WithRequest(ctx, req)
GetRequestLogger(ctx).Infof("request variables")

Like above, if we want to include the request data in all log messages in the context, we push the logger to a new context and use that one:

ctx = WithLogger(ctx, GetRequestLogger(ctx))

The concept is fairly powerful and ensures that calls throughout the stack can be traced in log messages. Using the fields like "http.request.id", one can analyze call flow for a particular request with a simple grep of the logs.

Index

• Variables
• func GetRequest(ctx Context) (*http.Request, error)
• func GetRequestID(ctx Context) string
• func GetResponseWriter(ctx Context) (http.ResponseWriter, error)
• func GetStringValue(ctx Context, key interface{}) (value string)
• func GetVersion(ctx Context) string
• func RemoteAddr(r *http.Request) string
• func RemoteIP(r *http.Request) string
• func Since(ctx Context, key interface{}) time.Duration
• func WithValues(ctx context.Context, m map[string]interface{}) context.Context
• type Context
  • func Background() Context
  • func WithLogger(ctx Context, logger Logger) Context
  • func WithRequest(ctx Context, r *http.Request) Context
  • func WithResponseWriter(ctx Context, w http.ResponseWriter) (Context, http.ResponseWriter)
  • func WithTrace(ctx Context) (Context, func(format string, a ...interface{}))
  • func WithValue(parent Context, key, val interface{}) Context
  • func WithVars(ctx Context, r *http.Request) Context
  • func WithVersion(ctx Context, version string) Context
• type Logger
  • func GetLogger(ctx Context, keys ...interface{}) Logger
  • func GetLoggerWithField(ctx Context, key, value interface{}, keys ...interface{}) Logger
  • func GetLoggerWithFields(ctx Context, fields map[interface{}]interface{}, keys ...interface{}) Logger
  • func GetRequestLogger(ctx Context) Logger
  • func GetResponseLogger(ctx Context) Logger

Variables

var (
	ErrNoRequestContext        = errors.New("no http request in context")
	ErrNoResponseWriterContext = errors.New("no http response in context")
)

Common errors used with this package.

Functions

func GetRequest

func GetRequest(ctx Context) (*http.Request, error)

GetRequest returns the http request in the given context. Returns ErrNoRequestContext if the context does not have an http request associated with it.

func GetRequestID

func GetRequestID(ctx Context) string

GetRequestID attempts to resolve the current request id, if possible. An error is return if it is not available on the context.

func GetResponseWriter

func GetResponseWriter(ctx Context) (http.ResponseWriter, error)

GetResponseWriter returns the http.ResponseWriter from the provided context. If not present, ErrNoResponseWriterContext is returned. The returned instance provides instrumentation in the context.

func GetStringValue

func GetStringValue(ctx Context, key interface{}) (value string)

GetStringValue returns a string value from the context. The empty string will be returned if not found.

func GetVersion

func GetVersion(ctx Context) string

GetVersion returns the application version from the context. An empty string may returned if the version was not set on the context.

func RemoteAddr

func RemoteAddr(r *http.Request) string

RemoteAddr extracts the remote address of the request, taking into account proxy headers.

func RemoteIP

func RemoteIP(r *http.Request) string

RemoteIP extracts the remote IP of the request, taking into account proxy headers.

func Since

func Since(ctx Context, key interface{}) time.Duration

Since looks up key, which should be a time.Time, and returns the duration since that time. If the key is not found, the value returned will be zero. This is helpful when inferring metrics related to context execution times.

func WithValues

func WithValues(ctx context.Context, m map[string]interface{}) context.Context

WithValues returns a context that proxies lookups through a map. Only supports string keys.

Types

type Context

type Context interface {
	context.Context
}

Context is a copy of Context from the golang.org/x/net/context package.

func Background

func Background() Context

Background returns a non-nil, empty Context. The background context provides a single key, "instance.id" that is globally unique to the process.

func WithLogger

func WithLogger(ctx Context, logger Logger) Context

WithLogger creates a new context with provided logger.

func WithRequest

func WithRequest(ctx Context, r *http.Request) Context

WithRequest places the request on the context. The context of the request is assigned a unique id, available at "http.request.id". The request itself is available at "http.request". Other common attributes are available under the prefix "http.request.". If a request is already present on the context, this method will panic.

func WithResponseWriter

func WithResponseWriter(ctx Context, w http.ResponseWriter) (Context, http.ResponseWriter)

WithResponseWriter returns a new context and response writer that makes interesting response statistics available within the context.

func WithTrace

func WithTrace(ctx Context) (Context, func(format string, a ...interface{}))

WithTrace allocates a traced timing span in a new context. This allows a caller to track the time between calling WithTrace and the returned done function. When the done function is called, a log message is emitted with a "trace.duration" field, corresponding to the elapsed time and a "trace.func" field, corresponding to the function that called WithTrace.

The logging keys "trace.id" and "trace.parent.id" are provided to implement dapper-like tracing. This function should be complemented with a WithSpan method that could be used for tracing distributed RPC calls.

The main benefit of this function is to post-process log messages or intercept them in a hook to provide timing data. Trace ids and parent ids can also be linked to provide call tracing, if so required.

Here is an example of the usage:

func timedOperation(ctx Context) {
	ctx, done := WithTrace(ctx)
	defer done("this will be the log message")
	// ... function body ...
}

If the function ran for roughly 1s, such a usage would emit a log message as follows:

INFO[0001] this will be the log message  trace.duration=1.004575763s trace.func=github.com/docker/distribution/context.traceOperation trace.id=<id> ...

Notice that the function name is automatically resolved, along with the package and a trace id is emitted that can be linked with parent ids.

func WithValue

func WithValue(parent Context, key, val interface{}) Context

WithValue returns a copy of parent in which the value associated with key is val. Use context Values only for request-scoped data that transits processes and APIs, not for passing optional parameters to functions.

func WithVars

func WithVars(ctx Context, r *http.Request) Context

WithVars extracts gorilla/mux vars and makes them available on the returned context. Variables are available at keys with the prefix "vars.". For example, if looking for the variable "name", it can be accessed as "vars.name". Implementations that are accessing values need not know that the underlying context is implemented with gorilla/mux vars.

func WithVersion

func WithVersion(ctx Context, version string) Context

WithVersion stores the application version in the context. The new context gets a logger to ensure log messages are marked with the application version.

type Logger

type Logger interface {
	// standard logger methods
	Print(args ...interface{})
	Printf(format string, args ...interface{})
	Println(args ...interface{})

	Fatal(args ...interface{})
	Fatalf(format string, args ...interface{})
	Fatalln(args ...interface{})

	Panic(args ...interface{})
	Panicf(format string, args ...interface{})
	Panicln(args ...interface{})

	// Leveled methods, from logrus
	Debug(args ...interface{})
	Debugf(format string, args ...interface{})
	Debugln(args ...interface{})

	Error(args ...interface{})
	Errorf(format string, args ...interface{})
	Errorln(args ...interface{})

	Info(args ...interface{})
	Infof(format string, args ...interface{})
	Infoln(args ...interface{})

	Warn(args ...interface{})
	Warnf(format string, args ...interface{})
	Warnln(args ...interface{})
}

Logger provides a leveled-logging interface.

func GetLogger

func GetLogger(ctx Context, keys ...interface{}) Logger

GetLogger returns the logger from the current context, if present. If one or more keys are provided, they will be resolved on the context and included in the logger. While context.Value takes an interface, any key argument passed to GetLogger will be passed to fmt.Sprint when expanded as a logging key field. If context keys are integer constants, for example, its recommended that a String method is implemented.

func GetLoggerWithField

func GetLoggerWithField(ctx Context, key, value interface{}, keys ...interface{}) Logger

GetLoggerWithField returns a logger instance with the specified field key and value without affecting the context. Extra specified keys will be resolved from the context.

func GetLoggerWithFields

func GetLoggerWithFields(ctx Context, fields map[interface{}]interface{}, keys ...interface{}) Logger

GetLoggerWithFields returns a logger instance with the specified fields without affecting the context. Extra specified keys will be resolved from the context.

func GetRequestLogger

func GetRequestLogger(ctx Context) Logger

GetRequestLogger returns a logger that contains fields from the request in the current context. If the request is not available in the context, no fields will display. Request loggers can safely be pushed onto the context.

func GetResponseLogger

func GetResponseLogger(ctx Context) Logger

GetResponseLogger reads the current response stats and builds a logger. Because the values are read at call time, pushing a logger returned from this function on the context will lead to missing or invalid data. Only call this at the end of a request, after the response has been written.