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

    Constants

    This section is empty.

    Variables

    View Source
    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].

      View Source
      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

          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.

                  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

                    func NewEventLog(family, title string) EventLog

                      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

                        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.