Source file src/net/http/pprof/pprof.go

     1	// Copyright 2010 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     4	
     5	// Package pprof serves via its HTTP server runtime profiling data
     6	// in the format expected by the pprof visualization tool.
     7	//
     8	// The package is typically only imported for the side effect of
     9	// registering its HTTP handlers.
    10	// The handled paths all begin with /debug/pprof/.
    11	//
    12	// To use pprof, link this package into your program:
    13	//	import _ "net/http/pprof"
    14	//
    15	// If your application is not already running an http server, you
    16	// need to start one. Add "net/http" and "log" to your imports and
    17	// the following code to your main function:
    18	//
    19	// 	go func() {
    20	// 		log.Println(http.ListenAndServe("localhost:6060", nil))
    21	// 	}()
    22	//
    23	// Then use the pprof tool to look at the heap profile:
    24	//
    25	//	go tool pprof http://localhost:6060/debug/pprof/heap
    26	//
    27	// Or to look at a 30-second CPU profile:
    28	//
    29	//	go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
    30	//
    31	// Or to look at the goroutine blocking profile, after calling
    32	// runtime.SetBlockProfileRate in your program:
    33	//
    34	//	go tool pprof http://localhost:6060/debug/pprof/block
    35	//
    36	// Or to collect a 5-second execution trace:
    37	//
    38	//	wget http://localhost:6060/debug/pprof/trace?seconds=5
    39	//
    40	// Or to look at the holders of contended mutexes, after calling
    41	// runtime.SetMutexProfileFraction in your program:
    42	//
    43	//	go tool pprof http://localhost:6060/debug/pprof/mutex
    44	//
    45	// To view all available profiles, open http://localhost:6060/debug/pprof/
    46	// in your browser.
    47	//
    48	// For a study of the facility in action, visit
    49	//
    50	//	https://blog.golang.org/2011/06/profiling-go-programs.html
    51	//
    52	package pprof
    53	
    54	import (
    55		"bufio"
    56		"bytes"
    57		"fmt"
    58		"html/template"
    59		"io"
    60		"log"
    61		"net/http"
    62		"os"
    63		"runtime"
    64		"runtime/pprof"
    65		"runtime/trace"
    66		"sort"
    67		"strconv"
    68		"strings"
    69		"time"
    70	)
    71	
    72	func init() {
    73		http.HandleFunc("/debug/pprof/", Index)
    74		http.HandleFunc("/debug/pprof/cmdline", Cmdline)
    75		http.HandleFunc("/debug/pprof/profile", Profile)
    76		http.HandleFunc("/debug/pprof/symbol", Symbol)
    77		http.HandleFunc("/debug/pprof/trace", Trace)
    78	}
    79	
    80	// Cmdline responds with the running program's
    81	// command line, with arguments separated by NUL bytes.
    82	// The package initialization registers it as /debug/pprof/cmdline.
    83	func Cmdline(w http.ResponseWriter, r *http.Request) {
    84		w.Header().Set("X-Content-Type-Options", "nosniff")
    85		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    86		fmt.Fprintf(w, strings.Join(os.Args, "\x00"))
    87	}
    88	
    89	func sleep(w http.ResponseWriter, d time.Duration) {
    90		var clientGone <-chan bool
    91		if cn, ok := w.(http.CloseNotifier); ok {
    92			clientGone = cn.CloseNotify()
    93		}
    94		select {
    95		case <-time.After(d):
    96		case <-clientGone:
    97		}
    98	}
    99	
   100	func durationExceedsWriteTimeout(r *http.Request, seconds float64) bool {
   101		srv, ok := r.Context().Value(http.ServerContextKey).(*http.Server)
   102		return ok && srv.WriteTimeout != 0 && seconds >= srv.WriteTimeout.Seconds()
   103	}
   104	
   105	func serveError(w http.ResponseWriter, status int, txt string) {
   106		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
   107		w.Header().Set("X-Go-Pprof", "1")
   108		w.Header().Del("Content-Disposition")
   109		w.WriteHeader(status)
   110		fmt.Fprintln(w, txt)
   111	}
   112	
   113	// Profile responds with the pprof-formatted cpu profile.
   114	// Profiling lasts for duration specified in seconds GET parameter, or for 30 seconds if not specified.
   115	// The package initialization registers it as /debug/pprof/profile.
   116	func Profile(w http.ResponseWriter, r *http.Request) {
   117		w.Header().Set("X-Content-Type-Options", "nosniff")
   118		sec, err := strconv.ParseInt(r.FormValue("seconds"), 10, 64)
   119		if sec <= 0 || err != nil {
   120			sec = 30
   121		}
   122	
   123		if durationExceedsWriteTimeout(r, float64(sec)) {
   124			serveError(w, http.StatusBadRequest, "profile duration exceeds server's WriteTimeout")
   125			return
   126		}
   127	
   128		// Set Content Type assuming StartCPUProfile will work,
   129		// because if it does it starts writing.
   130		w.Header().Set("Content-Type", "application/octet-stream")
   131		w.Header().Set("Content-Disposition", `attachment; filename="profile"`)
   132		if err := pprof.StartCPUProfile(w); err != nil {
   133			// StartCPUProfile failed, so no writes yet.
   134			serveError(w, http.StatusInternalServerError,
   135				fmt.Sprintf("Could not enable CPU profiling: %s", err))
   136			return
   137		}
   138		sleep(w, time.Duration(sec)*time.Second)
   139		pprof.StopCPUProfile()
   140	}
   141	
   142	// Trace responds with the execution trace in binary form.
   143	// Tracing lasts for duration specified in seconds GET parameter, or for 1 second if not specified.
   144	// The package initialization registers it as /debug/pprof/trace.
   145	func Trace(w http.ResponseWriter, r *http.Request) {
   146		w.Header().Set("X-Content-Type-Options", "nosniff")
   147		sec, err := strconv.ParseFloat(r.FormValue("seconds"), 64)
   148		if sec <= 0 || err != nil {
   149			sec = 1
   150		}
   151	
   152		if durationExceedsWriteTimeout(r, sec) {
   153			serveError(w, http.StatusBadRequest, "profile duration exceeds server's WriteTimeout")
   154			return
   155		}
   156	
   157		// Set Content Type assuming trace.Start will work,
   158		// because if it does it starts writing.
   159		w.Header().Set("Content-Type", "application/octet-stream")
   160		w.Header().Set("Content-Disposition", `attachment; filename="trace"`)
   161		if err := trace.Start(w); err != nil {
   162			// trace.Start failed, so no writes yet.
   163			serveError(w, http.StatusInternalServerError,
   164				fmt.Sprintf("Could not enable tracing: %s", err))
   165			return
   166		}
   167		sleep(w, time.Duration(sec*float64(time.Second)))
   168		trace.Stop()
   169	}
   170	
   171	// Symbol looks up the program counters listed in the request,
   172	// responding with a table mapping program counters to function names.
   173	// The package initialization registers it as /debug/pprof/symbol.
   174	func Symbol(w http.ResponseWriter, r *http.Request) {
   175		w.Header().Set("X-Content-Type-Options", "nosniff")
   176		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
   177	
   178		// We have to read the whole POST body before
   179		// writing any output. Buffer the output here.
   180		var buf bytes.Buffer
   181	
   182		// We don't know how many symbols we have, but we
   183		// do have symbol information. Pprof only cares whether
   184		// this number is 0 (no symbols available) or > 0.
   185		fmt.Fprintf(&buf, "num_symbols: 1\n")
   186	
   187		var b *bufio.Reader
   188		if r.Method == "POST" {
   189			b = bufio.NewReader(r.Body)
   190		} else {
   191			b = bufio.NewReader(strings.NewReader(r.URL.RawQuery))
   192		}
   193	
   194		for {
   195			word, err := b.ReadSlice('+')
   196			if err == nil {
   197				word = word[0 : len(word)-1] // trim +
   198			}
   199			pc, _ := strconv.ParseUint(string(word), 0, 64)
   200			if pc != 0 {
   201				f := runtime.FuncForPC(uintptr(pc))
   202				if f != nil {
   203					fmt.Fprintf(&buf, "%#x %s\n", pc, f.Name())
   204				}
   205			}
   206	
   207			// Wait until here to check for err; the last
   208			// symbol will have an err because it doesn't end in +.
   209			if err != nil {
   210				if err != io.EOF {
   211					fmt.Fprintf(&buf, "reading request: %v\n", err)
   212				}
   213				break
   214			}
   215		}
   216	
   217		w.Write(buf.Bytes())
   218	}
   219	
   220	// Handler returns an HTTP handler that serves the named profile.
   221	func Handler(name string) http.Handler {
   222		return handler(name)
   223	}
   224	
   225	type handler string
   226	
   227	func (name handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
   228		w.Header().Set("X-Content-Type-Options", "nosniff")
   229		p := pprof.Lookup(string(name))
   230		if p == nil {
   231			serveError(w, http.StatusNotFound, "Unknown profile")
   232			return
   233		}
   234		gc, _ := strconv.Atoi(r.FormValue("gc"))
   235		if name == "heap" && gc > 0 {
   236			runtime.GC()
   237		}
   238		debug, _ := strconv.Atoi(r.FormValue("debug"))
   239		if debug != 0 {
   240			w.Header().Set("Content-Type", "text/plain; charset=utf-8")
   241		} else {
   242			w.Header().Set("Content-Type", "application/octet-stream")
   243			w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"`, name))
   244		}
   245		p.WriteTo(w, debug)
   246	}
   247	
   248	var profileDescriptions = map[string]string{
   249		"allocs":       "A sampling of all past memory allocations",
   250		"block":        "Stack traces that led to blocking on synchronization primitives",
   251		"cmdline":      "The command line invocation of the current program",
   252		"goroutine":    "Stack traces of all current goroutines",
   253		"heap":         "A sampling of memory allocations of live objects. You can specify the gc GET parameter to run GC before taking the heap sample.",
   254		"mutex":        "Stack traces of holders of contended mutexes",
   255		"profile":      "CPU profile. You can specify the duration in the seconds GET parameter. After you get the profile file, use the go tool pprof command to investigate the profile.",
   256		"threadcreate": "Stack traces that led to the creation of new OS threads",
   257		"trace":        "A trace of execution of the current program. You can specify the duration in the seconds GET parameter. After you get the trace file, use the go tool trace command to investigate the trace.",
   258	}
   259	
   260	// Index responds with the pprof-formatted profile named by the request.
   261	// For example, "/debug/pprof/heap" serves the "heap" profile.
   262	// Index responds to a request for "/debug/pprof/" with an HTML page
   263	// listing the available profiles.
   264	func Index(w http.ResponseWriter, r *http.Request) {
   265		if strings.HasPrefix(r.URL.Path, "/debug/pprof/") {
   266			name := strings.TrimPrefix(r.URL.Path, "/debug/pprof/")
   267			if name != "" {
   268				handler(name).ServeHTTP(w, r)
   269				return
   270			}
   271		}
   272	
   273		type profile struct {
   274			Name  string
   275			Href  string
   276			Desc  string
   277			Count int
   278		}
   279		var profiles []profile
   280		for _, p := range pprof.Profiles() {
   281			profiles = append(profiles, profile{
   282				Name:  p.Name(),
   283				Href:  p.Name() + "?debug=1",
   284				Desc:  profileDescriptions[p.Name()],
   285				Count: p.Count(),
   286			})
   287		}
   288	
   289		// Adding other profiles exposed from within this package
   290		for _, p := range []string{"cmdline", "profile", "trace"} {
   291			profiles = append(profiles, profile{
   292				Name: p,
   293				Href: p,
   294				Desc: profileDescriptions[p],
   295			})
   296		}
   297	
   298		sort.Slice(profiles, func(i, j int) bool {
   299			return profiles[i].Name < profiles[j].Name
   300		})
   301	
   302		if err := indexTmpl.Execute(w, profiles); err != nil {
   303			log.Print(err)
   304		}
   305	}
   306	
   307	var indexTmpl = template.Must(template.New("index").Parse(`<html>
   308	<head>
   309	<title>/debug/pprof/</title>
   310	<style>
   311	.profile-name{
   312		display:inline-block;
   313		width:6rem;
   314	}
   315	</style>
   316	</head>
   317	<body>
   318	/debug/pprof/<br>
   319	<br>
   320	Types of profiles available:
   321	<table>
   322	<thead><td>Count</td><td>Profile</td></thead>
   323	{{range .}}
   324		<tr>
   325		<td>{{.Count}}</td><td><a href={{.Href}}>{{.Name}}</a></td>
   326		</tr>
   327	{{end}}
   328	</table>
   329	<a href="goroutine?debug=2">full goroutine stack dump</a>
   330	<br/>
   331	<p>
   332	Profile Descriptions:
   333	<ul>
   334	{{range .}}
   335	<li><div class=profile-name>{{.Name}}:</div> {{.Desc}}</li>
   336	{{end}}
   337	</ul>
   338	</p>
   339	</body>
   340	</html>
   341	`))
   342	

View as plain text