trace

Documentation

Overview

Package trace implements tracing of requests. It exports an HTTP interface on /debug/requests.

A request handler might be implemented like this:

func myHandler(w http.ResponseWriter, req *http.Request) {
	tr := trace.New("Received", req.URL.Path)
	defer tr.Finish()
	...
	tr.LazyPrintf("some event %q happened", str)
	...
	if err := somethingImportant(); err != nil {
		tr.LazyPrintf("somethingImportant failed: %v", err)
		tr.SetError()
	}
}

Index

• Variables
• type Trace
  • func New(family, title string) Trace

Variables

var AuthRequest = func(req *http.Request) (any, sensitive bool) {
	host, _, err := net.SplitHostPort(req.RemoteAddr)
	switch {
	case err != nil:
		return false, false
	case host == "localhost" || host == "127.0.0.1" || host == "::1":
		return true, true
	default:
		return false, false
	}
}

AuthRequest determines whether a specific request is permitted to load the /debug/requests page. It returns two bools; the first indicates whether the page may be viewed at all, and the second indicates whether sensitive events will be shown.

AuthRequest may be replaced by a program to customise its authorisation requirements.

The default AuthRequest function returns (true, true) iff the request comes from localhost/127.0.0.1/[::1].

var DebugUseAfterFinish = false

DebugUseAfterFinish controls whether to debug uses of Trace values after finishing. FOR DEBUGGING ONLY. This will slow down the program.

Types

type Trace

type Trace interface {
	// LazyLog adds x to the event log. It will be evaluated each time the
	// /debug/requests page is rendered. Any memory referenced by x will be
	// pinned until the trace is finished and later discarded.
	LazyLog(x fmt.Stringer, sensitive bool)

	// LazyPrintf evaluates its arguments with fmt.Sprintf each time the
	// /debug/requests page is rendered. Any memory referenced by a will be
	// pinned until the trace is finished and later discarded.
	LazyPrintf(format string, a ...interface{})

	// SetError declares that this trace resulted in an error.
	SetError()

	// SetRecycler sets a recycler for the trace.
	// f will be called for each event passed to LazyLog at a time when
	// it is no longer required, whether while the trace is still active
	// and the event is discarded, or when a completed trace is discarded.
	SetRecycler(f func(interface{}))

	// SetTraceInfo sets the trace info for the trace.
	// This is currently unused.
	SetTraceInfo(traceID, spanID uint64)

	// SetMaxEvents sets the maximum number of events that will be stored
	// in the trace. This has no effect if any events have already been
	// added to the trace.
	SetMaxEvents(m int)

	// Finish declares that this trace is complete.
	// The trace should not be used after calling this method.
	Finish()
}

Trace represents an active request.

func New

func New(family, title string) Trace

New returns a new Trace with the specified family and title.