package trace

Import Path
	golang.org/x/net/trace (on go.dev)

Dependency Relation
	imports 19 packages, and imported by 2 packages


Involved Source Files

	      events.go
	      histogram.go
	
		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.


Package-Level Type Names (total 22, in which 2 are exported)


	/* sort exporteds by:  |  */
	
		An EventLog provides a log of events associated with a specific object.

		
			
				Errorf is like Printf, but it marks this event as an error.

			
				Finish declares that this event log is complete.
				The event log should not be used after calling this method.

			
				Printf formats its arguments with fmt.Sprintf and adds the
				result to the event log.

		
			
		
			func NewEventLog(family, title string) EventLog


	
		Trace represents an active request.

		
			
				Finish declares that this trace is complete.
				The trace should not be used after calling this method.

			
				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.

			
				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.

			
				SetError declares that this trace resulted in an error.

			
				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.

			
				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.

			
				SetTraceInfo sets the trace info for the trace.
				This is currently unused.

		
			
		
			func FromContext(ctx context.Context) (tr Trace, ok bool)
			func New(family, title string) Trace
		
			func NewContext(ctx context.Context, tr Trace) context.Context


	


Package-Level Functions (total 30, in which 8 are exported)


	
		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.


	
		FromContext returns the Trace bound to the context, if any.


	
		New returns a new Trace with the specified family and title.


	
		NewContext returns a copy of the parent context
		and associates it with a Trace.


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


	
		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.


	
		Traces responds with traces from the program.
		The package initialization registers it in http.DefaultServeMux
		at /debug/requests.

		It performs authorization by running AuthRequest.


	


Package-Level Variables (total 18, in which 2 are exported)


	
		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.


	


Package-Level Constants (total 12, none are exported)