debug

README

debug: Inspect Microservices at Runtime

Overview

Package debug provides a few functions to help debug microservices. The functions make it possible to toggle debug logs on and off at runtime, to log the content of request and result payloads, and to profile a microservice.

Usage

Toggling Debug Logs

The debug package provides a MountDebugLogEnabler function which adds a handler to the given mux under the /debug path that accepts requests of the form /debug?debug-logs=on and /debug?debug-logs=off to manage debug logs state. The handler returns the current state of debug logs in the response body and does not change the state if the request does not contain a debug-logs query parameter. The path, query parameter name and value can be customized by passing options to the MountDebugLogEnabler function.

Note that for the debug log state to take effect, HTTP servers must use handlers returned by the HTTP function and gRPC servers must make use of the UnaryInterceptor or StreamInterceptor interceptors. Also note that gRPC services must expose an HTTP endpoint to control the debug log state.

// HTTP
mux := http.NewServeMux()
debug.MountDebugLogEnabler(mux)
// ... configure mux with other handlers
srv := &http.Server{Handler: debug.HTTP(mux)}
srv.ListenAndServe()

// gRPC
mux := http.NewServeMux()
debug.MountDebugLogEnabler(mux)
srv := &http.Server{Handler: mux}
go srv.ListenAndServe()
gsrv := grpc.NewServer(grpc.UnaryInterceptor(debug.UnaryInterceptor))
lis, _ := net.Listen("tcp", ":8080")
gsrv.Serve(lis)

The package also provides a Goa muxer adapter that can be used to mount the debug log enabler handler on a Goa muxer.

mux := goa.NewMuxer()
debug.MountDebugLogEnabler(debug.Adapt(mux))

Logging Request and Result Payloads

The debug package provides a LogPayloads Goa endpoint middleware that logs the content of request and result payloads. The middleware can be used with the generated Use functions on Endpoints structs. The middleware is a no-op if debug logs are disabled.

endpoints := genforecaster.NewEndpoints(svc)
endpoints.Use(debug.LogPayloads())
endpoints.Use(log.Endpoint)

Profiling

The debug package provides a MountPprofHandlers function which configures a given mux to serve the pprof handlers under the /debug/pprof/ URL prefix. The list of handlers is:

• /debug/pprof/
• /debug/pprof/allocs
• /debug/pprof/block
• /debug/pprof/cmdline
• /debug/pprof/goroutine
• /debug/pprof/heap
• /debug/pprof/mutex
• /debug/pprof/profile
• /debug/pprof/symbol
• /debug/pprof/threadcreate
• /debug/pprof/trace

See the net/http/pprof package documentation for more information.

The path prefix can be customized by passing an option to the MountPprofHandlers function.

mux := http.NewServeMux()
debug.MountPprofHandlers(mux)
// ... configure mux with other handlers

Example

The weather example illustrates how to make use of this package. In particular all the services allow for toggling debug logs on or off dynamically (see toggle HTTP endpoint being mounted here and gRPC interceptor managing log level being added here) and will log the content of request and result payloads when debug logs are enabled (see Goa endpoint middleware being used here). Additionally the two "back" services (which would not be exposed to the internet in production) also mount the pprof handlers (see here). With this setup, requests made to the HTTP servers of each service of the form /debug?debug-logs=on turn on debug logs and requests of the form /debug?debug-logs=off turns them back off. Requests made to /debug/pprof/ return the pprof package index page while a request to /debug/pprof/profile profile the service for 30s.

Documentation

Index

• Constants
• func FormatJSON(_ context.Context, v interface{}) string
• func HTTP() func(http.Handler) http.Handler
• func LogPayloads(opts ...LogPayloadsOption) func(goa.Endpoint) goa.Endpoint
• func MountDebugLogEnabler(mux Muxer, opts ...DebugLogEnablerOption)
• func MountPprofHandlers(mux Muxer, opts ...PprofOption)
• func StreamServerInterceptor() grpc.StreamServerInterceptor
• func UnaryServerInterceptor() grpc.UnaryServerInterceptor
• type DebugLogEnablerOption
  • func WithOffValue(offval string) DebugLogEnablerOption
  • func WithOnValue(onval string) DebugLogEnablerOption
  • func WithPath(path string) DebugLogEnablerOption
  • func WithQuery(query string) DebugLogEnablerOption
• type FormatFunc
• type LogPayloadsOption
  • func WithClient() LogPayloadsOption
  • func WithFormat(fn FormatFunc) LogPayloadsOption
  • func WithMaxSize(n int) LogPayloadsOption
• type Muxer
  • func Adapt(m goahttp.Muxer) Muxer
• type PprofOption
  • func WithPrefix(prefix string) PprofOption

Constants

const DefaultMaxSize = 1024

DefaultMaxSize is the default maximum size for a logged request or result value in bytes used by LogPayloads.

Functions

func FormatJSON

func FormatJSON(_ context.Context, v interface{}) string

FormatJSON returns a function that formats the given value as JSON.

func HTTP

func HTTP() func(http.Handler) http.Handler

HTTP returns a middleware that manages whether debug log entries are written. This middleware should be used in conjunction with the MountDebugLogEnabler function.

func LogPayloads

func LogPayloads(opts ...LogPayloadsOption) func(goa.Endpoint) goa.Endpoint

LogPayloads returns a Goa endpoint middleware that logs request payloads and response results using debug log entries.

Note: this middleware marshals the request and response data using the standard JSON marshaller. It only marshals if debug logs are enabled.

func MountDebugLogEnabler

func MountDebugLogEnabler(mux Muxer, opts ...DebugLogEnablerOption)

MountDebugLogEnabler mounts an endpoint under "/debug" that manages the status of debug logs. The endpoint accepts a single query parameter "debug-logs". If the parameter is set to "on" then debug logs are enabled. If the parameter is set to "off" then debug logs are disabled. In all other cases the endpoint returns the current debug logs status. The path, query parameter name and values can be changed using the WithPath, WithQuery, WithOnValue and WithOffValue options.

Note: the endpoint merely controls the status of debug logs. It does not actually configure the current logger. The logger is configured by the middleware returned by the HTTP function or by the gRPC interceptors returned by the UnaryServerInterceptor and StreamServerInterceptor functions which should be used in conjunction with the MountDebugLogEnabler function.

func MountPprofHandlers

func MountPprofHandlers(mux Muxer, opts ...PprofOption)

MountPprofHandlers mounts pprof handlers under /debug/pprof/. The list of mounted handlers is:

/debug/pprof/
/debug/pprof/allocs
/debug/pprof/block
/debug/pprof/cmdline
/debug/pprof/goroutine
/debug/pprof/heap
/debug/pprof/mutex
/debug/pprof/profile
/debug/pprof/symbol
/debug/pprof/threadcreate
/debug/pprof/trace

See the pprof package documentation for more information.

The path prefix ("/debug/pprof/") can be changed using WithPprofPrefix. Note: do not call this function on production servers accessible to the public! It exposes sensitive information about the server.

func StreamServerInterceptor

func StreamServerInterceptor() grpc.StreamServerInterceptor

StreamServerInterceptor returns a stream interceptor that manages whether debug log entries are written. Note: a change in the debug setting is effective only for the next stream request. This interceptor should be used in conjunction with the MountDebugLogEnabler function.

func UnaryServerInterceptor

func UnaryServerInterceptor() grpc.UnaryServerInterceptor

UnaryServerInterceptor return an interceptor that manages whether debug log entries are written. This interceptor should be used in conjunction with the MountDebugLogEnabler function.

Types

type DebugLogEnablerOption

type DebugLogEnablerOption func(*dleOptions)

DebugLogEnablerOption is a function that applies a configuration option to MountDebugLogEnabler.

func WithOffValue

func WithOffValue(offval string) DebugLogEnablerOption

WithOffValue sets the query string parameter value used by MountDebugLogEnabler to disable debug logs.

func WithOnValue

func WithOnValue(onval string) DebugLogEnablerOption

WithOnValue sets the query string parameter value used by MountDebugLogEnabler to enable debug logs.

func WithPath

func WithPath(path string) DebugLogEnablerOption

WithPath sets the URL path used by MountDebugLogEnabler.

func WithQuery

func WithQuery(query string) DebugLogEnablerOption

WithQuery sets the query string parameter name used by MountDebugLogEnabler to enable or disable debug logs.

type FormatFunc

type FormatFunc func(context.Context, interface{}) string

FormatFunc is used to format the logged value for payloads and results.

type LogPayloadsOption

type LogPayloadsOption func(*lpOptions)

LogPayloadsOption is a function that applies a configuration option to the LogPayloads middleware.

func WithClient

func WithClient() LogPayloadsOption

WithClient prefixes the log keys used by LogPayloads with "client-". This is useful when logging client requests and responses.

func WithFormat

func WithFormat(fn FormatFunc) LogPayloadsOption

WithFormat sets the log format used by LogPayloads.

func WithMaxSize

func WithMaxSize(n int) LogPayloadsOption

WithMaxSize sets the maximum size of a single log message or value used by LogPayloads.

type Muxer

type Muxer interface {
	http.Handler
	Handle(pattern string, handler http.Handler)
	HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
}

Muxer is the HTTP mux interface used by the debug package.

func Adapt

func Adapt(m goahttp.Muxer) Muxer

Adapt returns a debug.Muxer adapter for the given goahttp.Muxer.

type PprofOption

type PprofOption func(*pprofOptions)

PprofOption is a function that applies a configuration option to MountPprofHandlers.

func WithPrefix

func WithPrefix(prefix string) PprofOption

WIthPrefix sets the path prefix used by MountPprofHandlers.