nettrace

Documentation

Overview

Package nettrace implements tracing of requests. Traces are created by nettrace.New, and can then be viewed over HTTP on /debug/traces.

Index

• Variables
• func NewContext(ctx context.Context, tr Trace) context.Context
• func RegisterHandler(mux *http.ServeMux)
• func RenderTraces(w http.ResponseWriter, req *http.Request)
• type Trace
  • func ChildFromContext(ctx context.Context, family, title string) Trace
  • func FromContext(ctx context.Context) (Trace, bool)
  • func FromContextOrNew(ctx context.Context, family, title string) (Trace, context.Context)
  • func New(family, title string) Trace

Variables

var Disable = false

Disable is a flag to disable all tracing functions. It can be used to minimize the performance impact of the tracing functions when they are not needed (e.g. no debug server or logging).

var Log func(family, title, id, msg string, err bool) = nil

To allow users to log the trace data, we provide a simple logging interface. This is global and not lock-protected, so if used, it must be set before any tracing is done.

Functions

func NewContext

func NewContext(ctx context.Context, tr Trace) context.Context

NewContext returns a new context with the given trace attached.

func RegisterHandler

func RegisterHandler(mux *http.ServeMux)

RegisterHandler registers a the trace handler in the given ServeMux, on `/debug/traces`.

func RenderTraces

func RenderTraces(w http.ResponseWriter, req *http.Request)

RenderTraces is an http.Handler that renders the tracing information.

Types

type Trace

type Trace interface {
	// NewChild creates a new trace, that is a child of this one.
	NewChild(family, title string) Trace

	// Link to another trace with the given message.
	Link(other Trace, msg string)

	// SetMaxEvents sets the maximum number of events that will be stored in
	// the trace. It must be called right after initialization.
	SetMaxEvents(n int)

	// SetError marks that the trace was for an error event.
	SetError()

	// Print adds a message to the trace.
	Print(s string)

	// Printf adds a formatted message to the trace.
	Printf(format string, a ...interface{})

	// Error logs an error to the trace, and returns it unchanged (for
	// convenience).
	Error(err error) error

	// Errorf adds a message to the trace, marks it as an error, and returns
	// an error for it.
	Errorf(format string, a ...interface{}) error

	// Finish marks the trace as complete.
	// The trace should not be used after calling this method.
	Finish()
}

Trace represents a single request trace.

func ChildFromContext

func ChildFromContext(ctx context.Context, family, title string) Trace

ChildFromContext returns a new trace that is a child of the one attached to the context (if any).

func FromContext

func FromContext(ctx context.Context) (Trace, bool)

FromContext returns the trace attached to the given context (if any).

func FromContextOrNew

func FromContextOrNew(ctx context.Context, family, title string) (Trace, context.Context)

FromContextOrNew returns the trace attached to the given context, or a new trace if there is none.

func New

func New(family, title string) Trace

New creates a new trace with the given family and title.