route/vendor/github.com/Xe/gopreload/manhole/README.md

manhole

An opinionated HTTP manhole into Go processes.

Assumptions This Package Makes

• Make each server instance have a unique HTTP port that is randomized by default. This makes it very hard to accidentally route this manhole to the outside world. If more assurance is required I personally suggest using yubikey totp, but do research.
• Application code does not touch http.DefaultServeMux'. This is so that administative control rods can be dynamically flipped in the case they are needed.
• pprof endpoints added to http.DefaultServeMux. This allows easy access to [pprof runtime tracing][pprof-tracing] to debug issues on long-running applications like HTTP services.
• Make the manhole slightly inconvenient to put into place in production. This helps make sure that this tool remains a debugging tool and not a part of a long-term production rollout.

Usage

Compile this as a plugin:

$ go get -d github.com/Xe/gopreload/manhole
$ go build -buildmode plugin -o manhole.so github.com/Xe/gopreload/manhole

Then add gopreload to your application:

// gopreload.go
package main

/*
    This file is separate to make it very easy to both add into an application, but
    also very easy to remove.
*/

import _ "github.com/Xe/gopreload"

And at runtime add the manhole.so file you created earlier to the target system somehow and add the following environment variable to its run configuration:

GO_PRELOAD=/path/to/manhole.so

---