diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index d1dda4374ff..cbb5a7a5697 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -95,6 +95,7 @@ - [completion](./reference/completion.md) - [Artifacts](./reference/artifacts.md) - [Platform Support](./reference/platform.md) + - [Monitoring with Pprof](./reference/pprof-tutorial.md) - [Manager and CRDs Scope](./reference/scopes.md) 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..9f332781fcf --- /dev/null +++ b/docs/book/src/reference/pprof-tutorial.md @@ -0,0 +1,62 @@ +# Monitoring Performance with Pprof + +[Pprof][pprof-go-docs], a Go profiling tool, helps identify performance bottlenecks in areas like CPU and memory usage. It's integrated with the controller-runtime library's HTTP server, enabling profiling via HTTP endpoints. You can visualize the data using go tool pprof. Since [Pprof][pprof-go-docs] is built into controller-runtime, no separate installation is needed. [Manager options][manager-options-doc] make it easy to enable pprof and gather runtime metrics to optimize controller performance. + + + +## How to use Pprof? + +1. **Enabling Pprof** + + In your `cmd/main.go` file, add the field: + + ```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** + + Using `curl`, 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 results will vary depending on the deployed workload, and the Controller's behavior. + However, you'll see the 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 +[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..18b5fe39ad1 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) + - [Monitoring with Pprof](pprof-tutorial.md) - [controller-gen CLI](controller-gen.md) - [completion](completion.md) - [Artifacts](artifacts.md)