Boundary
Enable debug mode
The debug flag enables debug mode. Debug mode exposes pprof endpoints on the ops listener.
Gathering information about the state of the Boundary cluster often requires the
operator to access all necessary information using API calls and terminal
commands. The debug flag offers a simple workflow that produces consistent output to help operators retrieve and share information about the controller or worker server in question.
Go's runtime/trace package can record execution traces that include user-defined regions. A region marks a time interval within a single goroutine, and you can nest regions to represent sequential steps in an operation.
Debug mode uses Go's runtime/trace package to expose execution trace data for Boundary. Boundary includes a small number of runtime tracing user regions, which you can use to see where Boundary spends its time during execution. Collecting a trace from the /debug/pprof/trace endpoint can help you identify latency bottlenecks, track logical operations, and correlate application-level logic with low-level runtime activity.
To create a trace you must expose a pprof endpoint. Boundary does not expose pprof endpoints by default. To expose a pprof endpoint you must enable the runtime -debug flag on a process with an ops listener.
Debug mode exposes the following pprof endpoints:
- /debug/pprof/
- /debug/pprof/heap
- /debug/pprof/profile
- /debug/pprof/block
- /debug/pprof/mutex
- /debug/pprof/goroutine
- /debug/pprof/threadcreate
- /debug/pprof/trace
- /debug/pprof/cmdline
- /debug/pprof/symbol
The debug flag honors the same variables that the base dev and server commands accept. You can use the debug flag with the server command to run a trace for controller and worker servers.
For more information about how to use the endpoints, refer to the pprof Go documentation and the trace package documentation.
Example
Here's an example of enabling debug using boundary dev:
$ boundary dev -debug -ops-listen-address=127.0.0.1:9203
This command exposes the pprof endpoints on the configured ops listener. In the preceding example, that means 127.0.0.1:9203, so users on the same machine can access the endpoints. This behavior is obvious for dev mode, but it also applies to the server command on controllers or workers.
Here's an example of enabling debug using boundary server:
$ boundary server -config=/etc/boundary.d/controller.hcl -debug -ops-listen-address=127.0.0.1:9203
To create a trace, use any tool that can create HTTP requests, for example curl. To create a 3 second trace:
$ curl -o trace.out http://127.0.0.1:9203/debug/pprof/trace?seconds=3
You can inspect the trace with go tool trace trace.out.
Traces are most useful when they contain request handling. Prepare HTTP requests that trigger the behavior you want to understand while the trace runs.