api docs for agent/pprof

website/source/api/agent.html.md

@@ -566,3 +566,77 @@ fields:
 
 - `Offset` - Offset is the offset into the stream.
 
+## Agent Runtime Profiles
+
+This endpoint is the equivalent of Go's /debug/pprof endpoint but is protected
+by ACLs and supports remote forwarding to a client node or server. See the
+[Golang documentation](https://golang.org/pkg/runtime/pprof/#Profile) for a list of available profiles.
+
+| Method | Path                          | Produces                   |
+| ------ | ----------------------------- | -------------------------- |
+| `GET`  | `/agent/pprof/cmdline`        | `text/plain`               |
+| `GET`  | `/agent/pprof/profile`        | `application/octet-stream` |
+| `GET`  | `/agent/pprof/trace`          | `application/octet-stream` |
+| `GET`  | `/agent/pprof/<pprof profile>`| `application/octet-stream` |
+
+The table below shows this endpoint's support for
+[blocking queries](/api/index.html#blocking-queries) and
+[required ACLs](/api/index.html#acls).
+
+| Blocking Queries | ACL Required  |
+| ---------------- | ------------- |
+| `NO`             | `agent:write` |
+
+### Default Behavior
+
+The default behavior of this endpoint complex but seeks to maximize security,
+backward compatibility, and still allow debug access by default when possible. 
+The table below outlines the different scenarios which will enable or disable
+the endpoint.
+
+|    Endpoint      |  `enable_debug`  |  ACLs  |  **Available?**  |
+|------------------|------------------|--------|------------------|
+| /v1/agent/pprof  |  unset           |  n/a   |  no              |
+| /v1/agent/pprof  |  `true`          |  n/a   |  yes             |
+| /v1/agent/pprof  |  `false`         |  n/a   |  no              |
+| /v1/agent/pprof  |  unset           |  off   |  no              |
+| /v1/agent/pprof  |  unset           |  on    |  **yes**         |
+| /v1/agent/pprof  |  `true`          |  off   |  yes             |
+| /v1/agent/pprof  |  `false`         |  n/a   |  **no**          |
+
+
+### Parameters
+
+- `node_id` `(string: "a57b2adb-1a30-2dda-8df0-25abb0881952")` - Specifies a text
+  string containing a node-id to target for streaming.
+
+- `server_id` `(string: "server1.global")` - Specifies a text
+  string containing a server id, name or "leader" to target a specific remote
+  server or leader for streaming.
+
+- `seconds` `(int: 3)` - Specifies the amount of time to run a profile or trace
+  request for.
+
+- `debug` `(int: 1)` - Specifies if a given pprof profile should be returned as
+  text/plain instead of application/octet-stream. Defaults to 0, setting to 1
+  enables.
+
+### Sample Request
+
+```text
+$ curl -O -J \
+    https://localhost:4646/v1/agent/pprof/goroutine?server_id=leader
+
+$ go tool pprof goroutine
+
+$ curl -O -J \
+    https://localhost:4646/v1/agent/profile?seconds=5&node_id=a57b2adb-1a30-2dda-8df0-25abb0881952
+
+$ go tool pprof profile
+
+$ curl -O -J \
+    https://localhost:4646/v1/agent/trace?&seconds=5&server_id=server1.global
+
+go tool trace trace
+```
+