package trace

import "golang.org/x/net/trace"

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

Package Files ¶

events.go histogram.go trace.go trace_go17.go

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.

func Events ¶ Uses

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 ¶ Uses

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 ¶ Uses

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 ¶ Uses

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 ¶ Uses

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.

type EventLog ¶ Uses

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 ¶ Uses

func NewEventLog(family, title string) EventLog

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

type Trace ¶ Uses

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 ¶ Uses

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

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

func New ¶ Uses

func New(family, title string) Trace

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