trace

Documentation

Overview

Package trace implements tracing of requests and long-lived objects. It exports HTTP interfaces on /debug/requests and /debug/events.

A trace.Trace provides tracing for short-lived objects, usually requests. A request handler might be implemented like this:

func fooHandler(w http.ResponseWriter, req *http.Request) {
	tr := trace.New("mypkg.Foo", 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()
	}
}

The /debug/requests HTTP endpoint organizes the traces by family, errors, and duration. It also provides histogram of request duration for each family.

A trace.EventLog provides tracing for long-lived objects, such as RPC connections.

// A Fetcher fetches URL paths for a single domain.
type Fetcher struct {
	domain string
	events trace.EventLog
}

func NewFetcher(domain string) *Fetcher {
	return &Fetcher{
		domain,
		trace.NewEventLog("mypkg.Fetcher", domain),
	}
}

func (f *Fetcher) Fetch(path string) (string, error) {
	resp, err := http.Get("http://" + f.domain + "/" + path)
	if err != nil {
		f.events.Errorf("Get(%q) = %v", path, err)
		return "", err
	}
	f.events.Printf("Get(%q) = %s", path, resp.Status)
	...
}

func (f *Fetcher) Close() error {
	f.events.Finish()
	return nil
}

The /debug/events HTTP endpoint organizes the event logs by family and by time since the last error. The expanded view displays recent log entries and the log's call stack.

Index

• Variables
• func Events(w http.ResponseWriter, req *http.Request)
• func NewContext(ctx context.Context, tr Trace) context.Context
• func Render(w io.Writer, req *http.Request, sensitive bool)
• func RenderEvents(w http.ResponseWriter, req *http.Request, sensitive bool)
• func Traces(w http.ResponseWriter, req *http.Request)
• type EventLog
  • func NewEventLog(family, title string) EventLog
• type Trace
  • func FromContext(ctx context.Context) (tr Trace, ok bool)
  • func New(family, title string) Trace

Variables

var AuthRequest = func(req *http.Request) (any, sensitive bool) {

	host, _, err := net.SplitHostPort(req.RemoteAddr)
	if err != nil {
		host = req.RemoteAddr
	}
	switch host {
	case "localhost", "127.0.0.1", "::1":
		return true, true
	default:
		return false, false
	}
}

AuthRequest determines whether a specific request is permitted to load the /debug/requests or /debug/events pages.

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 customize its authorization requirements.

The default AuthRequest function returns (true, true) if and only if 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.

Functions

func Events

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

Events responds with a page of events collected by EventLogs. The package initialization registers it in http.DefaultServeMux at /debug/events.

It performs authorization by running AuthRequest.

func NewContext

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

NewContext returns a copy of the parent context and associates it with a Trace.

func Render

func Render(w io.Writer, req *http.Request, sensitive bool)

Render renders the HTML page typically served at /debug/requests. It does not do any auth checking. The request may be nil.

Most users will use the Traces handler.

func RenderEvents

func RenderEvents(w http.ResponseWriter, req *http.Request, sensitive bool)

RenderEvents renders the HTML page typically served at /debug/events. It does not do any auth checking. The request may be nil.

Most users will use the Events handler.

func Traces

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

Traces responds with traces from the program. The package initialization registers it in http.DefaultServeMux at /debug/requests.

It performs authorization by running AuthRequest.

Types

type EventLog

type EventLog interface {
	// Printf formats its arguments with fmt.Sprintf and adds the
	// result to the event log.
	Printf(format string, a ...interface{})

	// Errorf is like Printf, but it marks this event as an error.
	Errorf(format string, a ...interface{})

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

An EventLog provides a log of events associated with a specific object.

func NewEventLog

func NewEventLog(family, title string) EventLog

NewEventLog returns a new EventLog with the specified family name and title.

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 FromContext

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

FromContext returns the Trace bound to the context, if any.

func New

func New(family, title string) Trace

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