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.
events.go histogram.go trace.go
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].
DebugUseAfterFinish controls whether to debug uses of Trace values after finishing. FOR DEBUGGING ONLY. This will slow down the program.
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.
NewContext returns a copy of the parent context and associates it with a Trace.
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.
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(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 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.
NewEventLog returns a new EventLog with the specified family name and title.
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.
FromContext returns the Trace bound to the context, if any.
New returns a new Trace with the specified family and title.
Package trace imports 19 packages (graph) and is imported by 844 packages. Updated 2020-12-25. Refresh now. Tools for package owners.