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
- type Trace
Constants ¶
This section is empty.
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 ¶
NewContext returns a copy of the parent context and associates it with a Trace.
func Render ¶
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.
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 ¶
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 ¶
FromContext returns the Trace bound to the context, if any.