Package netbug
provides access to an http.Handler
that accesses the profiling and debug tools available in the /net/http/pprof
and /runtime/pprof
packages.
The advantages of using netbug
over the existing /net/http/pprof
handlers are:
- You can register the handler under an arbitrary route-prefix. A use-case might be to have a secret endpoint for keeping this information hidden from prying eyes, rather than
/debug/pprof
; - It pulls together all the handlers from
/net/http/pprof
and/runtime/pprof
into a single index page, for when you can't quite remember the URL for the profile you want; - You can register the handlers onto
http.ServeMux
's that aren'thttp.DefaultServeMux
; - It provides an optional handler that requires a token URL parameter. This is useful if you want that little bit of extra security (use this over HTTPS connections only).
Note:
It still imports /net/http/pprof
, which means the /debug/pprof
routes in that package still get registered on http.DefaultServeMux
.
If you're using this package to avoid those routes being registered, you should use it with your own http.ServeMux
.
netbug
is trying to cater for the situation where you want all profiling tools available remotely on your running services, but you don't want to expose the /debug/pprof
routes that net/http/pprof
forces you to expose.
In the simplest case give netbug
the http.ServeMux
you want to register the handlers on, as well as where you want to register the handler and you're away.
package main
import (
"log"
"net/http"
"github.com/e-dard/netbug"
)
func main() {
r := http.NewServeMux()
netbug.RegisterHandler("/myroute/", r)
if err := http.ListenAndServe(":8080", r); err != nil {
log.Fatal(err)
}
}
Visiting https://localhost:8080/myroute/ will then return:
netbug
also provides a simple way of adding some authentication:
package main
import (
"log"
"net/http"
"github.com/e-dard/netbug"
)
func main() {
r := http.NewServeMux()
netbug.RegisterAuthHandler("password", "/myroute/", r)
if err := http.ListenAndServe(":8080", r); err != nil {
log.Fatal(err)
}
}
And visit https://localhost:8080/myroute/?token=password.
Obviously this form of authentication is pointless if you're not accessing the routes over an HTTPS connection.
If you want to use a different form of authentication, e.g., HTTP Basic Authentication, then you can use the handler returned by netbug.Handler()
, and wrap it with handlers provided by packages like github.com/abbot/go-http-auth.
It just wraps the behaviour of the /net/http/pprof and /runtime/pprof packages. Check out their documentation to see what's available. As an example though, if you want to run a 30-second CPU profile on your running service it's really simple:
$ go tool pprof https://example.com/myroute/profile
You can now produce execution traces of your remotely running program using netbug.
To do this run one of the trace profiles, which will result in a file being downloaded. Then use the Go trace
tool to generate a trace, which will open up in your browser.
$ go tool trace binary-being-profiled /path/to/downloaded/trace
When compiling binary-being-profiled
, you will need to have targeted the same architecture as the binary that generated the profile.
## Background
The net/http/pprof package is great.
It let's you access profiling and debug information about your running services, via HTTP
, and even plugs straight into go tool pprof
.
You can find out more about using the net/http/pprof
package at the bottom of this blog post.
However, there are a couple of problems with the net/http/pprof
package.
- It assumes you're cool about the relevant handlers being registered under the
/debug/pprof
route. - It assumes you're cool about handlers being registered on
http.DefaultServeMux
. - You can't wrap the handlers in any way, say to add authentication or other logic.
You can sort of fix (1) and (2) by digging around the net/http/pprof
package and registering all all the exported handlers under different paths on your own http.ServeMux
, but you still have the problem of the index page—which is useful to visit if you don't profile much—using hard-coded paths.
It doesn't really work well.
Also, the index page doesn't provide you with easy links to the debug information that the net/http/pprof
package has handlers for.
netbug
is just a small package to fix these issues.