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.
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.
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.
Source Files