| full goroutine stack dump
139 |
140 |
141 | `))
142 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # netbug
2 |
3 | [](https://godoc.org/github.com/e-dard/netbug)
4 |
5 | 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.
6 |
7 | The advantages of using `netbug` over the existing `/net/http/pprof` handlers are:
8 |
9 | 1. 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`;
10 | 2. 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;
11 | 3. You can register the handlers onto `http.ServeMux`'s that aren't `http.DefaultServeMux`;
12 | 4. 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).
13 |
14 | **Note**:
15 | It still imports `/net/http/pprof`, which means the `/debug/pprof` routes in that package *still* get registered on `http.DefaultServeMux`.
16 | If you're using this package to avoid those routes being registered, you should use it with your *own* `http.ServeMux`.
17 |
18 | `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.
19 |
20 | ## How do I use it?
21 | 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.
22 |
23 | ```go
24 | package main
25 |
26 | import (
27 | "log"
28 | "net/http"
29 |
30 | "github.com/e-dard/netbug"
31 | )
32 |
33 | func main() {
34 | r := http.NewServeMux()
35 | netbug.RegisterHandler("/myroute/", r)
36 | if err := http.ListenAndServe(":8080", r); err != nil {
37 | log.Fatal(err)
38 | }
39 | }
40 | ```
41 |
42 | Visiting [http://localhost:8080/myroute/](http://localhost:8080/myroute/) will then return:
43 |
44 | 
45 |
46 | `netbug` also provides a simple way of adding some authentication:
47 |
48 | ```go
49 | package main
50 |
51 | import (
52 | "log"
53 | "net/http"
54 |
55 | "github.com/e-dard/netbug"
56 | )
57 |
58 | func main() {
59 | r := http.NewServeMux()
60 | netbug.RegisterAuthHandler("password", "/myroute/", r)
61 | if err := http.ListenAndServe(":8080", r); err != nil {
62 | log.Fatal(err)
63 | }
64 | }
65 | ```
66 |
67 | And visit [http://localhost:8080/myroute/?token=password](http://localhost:8080/myroute/?token=password).
68 |
69 | **Obviously** this form of authentication is pointless if you're not accessing the routes over an HTTPS connection.
70 | 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](https://github.com/abbot/go-http-auth/).
71 |
72 | ### What can you do with it?
73 |
74 | It just wraps the behaviour of the [/net/http/pprof](http://golang.org/pkg/net/http/pprof/) and [/runtime/pprof](http://golang.org/pkg/runtime/pprof/) packages.
75 | Check out their documentation to see what's available.
76 | As an example though, if you want to run a 30-second CPU profile on your running service it's really simple:
77 |
78 | ```
79 | $ go tool pprof https://example.com/myroute/profile
80 | ```
81 |
82 | ##### New in Go 1.5
83 | You can now produce [execution traces](https://golang.org/pkg/runtime/trace/) of your remotely running program using netbug.
84 |
85 | 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.
86 |
87 | ```
88 | $ go tool trace binary-being-profiled /path/to/downloaded/trace
89 | ```
90 |
91 | When compiling `binary-being-profiled`, you will need to have targeted the same architecture as the binary that generated the profile.
92 |
93 | ## Background
94 | The [net/http/pprof](http://golang.org/pkg/net/http/pprof/) package is great.
95 | It let's you access profiling and debug information about your running services, via `HTTP`, and even plugs straight into `go tool pprof`.
96 | You can find out more about using the `net/http/pprof` package at the bottom of [this blog post](http://blog.golang.org/profiling-go-programs).
97 |
98 | However, there are a couple of problems with the `net/http/pprof` package.
99 |
100 | 1. It assumes you're cool about the relevant handlers being registered under the `/debug/pprof` route.
101 | 2. It assumes you're cool about handlers being registered on `http.DefaultServeMux`.
102 | 3. You can't wrap the handlers in any way, say to add authentication or other logic.
103 |
104 | 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.
105 | It doesn't really work well.
106 | Also, the index page doesn't provide you with easy links to the debug information that the `net/http/pprof` package has handlers for.
107 |
108 | `netbug` is just a small package to fix these issues.
109 |
110 |
--------------------------------------------------------------------------------
|