diff --git a/docs/book/src/reference/images/pprof-result-visualization.png b/docs/book/src/reference/images/pprof-result-visualization.png new file mode 100644 index 00000000000..a50fd1e4064 Binary files /dev/null and b/docs/book/src/reference/images/pprof-result-visualization.png differ diff --git a/docs/book/src/reference/pprof-tutorial.md b/docs/book/src/reference/pprof-tutorial.md new file mode 100644 index 00000000000..e7761ae89d9 --- /dev/null +++ b/docs/book/src/reference/pprof-tutorial.md @@ -0,0 +1,69 @@ +# Monitoring Performance with Pprof + +`pprof` is a Go profiling tool integrated within the `controller-runtime` library, designed to help identify performance bottlenecks in areas such as CPU usage, memory allocation, and more. This profiling tool, from the Go package [`net/http/pprof`][pprof-go-docs], is especially useful for diagnosing performance issues by providing detailed insights into resource usage during the runtime of your application. + +`pprof` is integrated into the HTTP server used by the `controller-runtime` manager, allowing you to collect profiling data via HTTP endpoints. This data can then be visualized using `go tool pprof`. Pprof feature is built into the `controller-runtime` library, so there is no need to install it separately. + +The `controller-runtime` [Manager options][manager-options-doc] provide an easy way to enable `pprof`, allowing you to gather detailed runtime metrics for improving the performance of your controllers. + +For further information about the Pprof, check out the official [Github repository][github-repo]. + + + +## How to use Pprof? + +1. **Enabling Pprof** + + In your `cmd/main.go` file, add the following `controller-runtime` manager field to enable the `pprof` endpoints: + + ```golang + mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{ + ... + // PprofBindAddress is the TCP address that the controller should bind to + // for serving pprof. Specify the manager address and the port that should be bind. + PprofBindAddress: ":8082", + ... + }) + ``` + +2. **Test It Out** + + After enabling [Pprof][pprof-go-docs], you need to build and deploy your controller to test it out. Follow the steps in the [Quick Start guide][quick-start-run-it] to run your project locally or on a cluster. + + Then, you can apply your CRs/samples in order to monitor the performance of its controllers. + +3. **Exporting the data** + + By using `curl`, we can export the profiling statistics to a file like this: + + ```bash + # Note that we are using the bind host and port configured via the + # Manager Options in the cmd/main.go + curl -s "http://127.0.0.1:8082/debug/pprof/profile" > ./cpu-profile.out + ``` + +4. **Visualizing the results on Browser** + + ```bash + # Go tool will open a session on port 8080. + # You can change this as per your own need. + go tool pprof -http=:8080 ./cpu-profile.out + ``` + + Visualizaion resutls will vary depending on the deployed workload, and the Controller's behavior. + However, you'll see a result on your browser similar to this one: + + ![pprof-result-visualization](./images/pprof-result-visualization.png) + +[pprof-go-docs]: https://pkg.go.dev/net/http/pprof +[manager-options-doc]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/manager +[github-repo]: https://github.com/google/pprof +[quick-start-run-it]: ../quick-start.md#test-it-out. diff --git a/docs/book/src/reference/reference.md b/docs/book/src/reference/reference.md index 1d9026777d8..31f01d763ef 100644 --- a/docs/book/src/reference/reference.md +++ b/docs/book/src/reference/reference.md @@ -27,6 +27,7 @@ - [Object/DeepCopy](markers/object.md) - [RBAC](markers/rbac.md) + - [Performance Profiling with Pprof](pprof-tutorial.md) - [controller-gen CLI](controller-gen.md) - [completion](completion.md) - [Artifacts](artifacts.md)