...
▽

Package trace

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

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.

Variables

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 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
    }
}

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

var DebugUseAfterFinish = false

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.

type EventLog

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

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()
}

func NewEventLog 

func NewEventLog(family, title string) EventLog

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

type Trace

Trace represents an active request. 

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()
}

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.