libgo/go/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 `))