pprof readme

Signed-off-by: Alec Holmes <[email protected]>

Author: alecholmez

Makefile

@@ -4,8 +4,8 @@
 # Variables
 #------------------------------------------------------------------------------
 
-SHELL 	:= /bin/bash
-BINDIR	:= bin
+SHELL 		:= /bin/bash
+BINDIR		:= bin
 PKG 		:= github.com/envoyproxy/go-control-plane
 
 .PHONY: build
@@ -19,6 +19,7 @@ clean:
 	@go mod tidy
 	@rm -rf $(BINDIR)
 	@rm -rf *.log
+	@rm -rf *.pprof
 
 # TODO(mattklein123): See the note in TestLinearConcurrentSetWatch() for why we set -parallel here
 # This should be removed.
@@ -74,10 +75,14 @@ integration.ads.delta: $(BINDIR)/test $(BINDIR)/upstream
 #------------------------------------------------------------------------------
 # Benchmarks utilizing intergration tests
 #------------------------------------------------------------------------------
-.PHONY: benchmark
+.PHONY: benchmark docker_benchmarks
 benchmark: $(BINDIR)/test $(BINDIR)/upstream
 	env XDS=xds MODE=$(MODE) build/integration.sh
 
+docker_benchmarks:
+	docker build --pull -f Dockerfile.ci . -t gcp_ci && \
+	docker run -v $$(pwd):/go-control-plane $$(tty -s && echo "-it" || echo) gcp_ci /bin/bash -c /go-control-plane/build/do_benchmarks.sh
+
 #--------------------------------------
 #-- example xDS control plane server
 #--------------------------------------
@@ -93,7 +98,3 @@ example: $(BINDIR)/example
 docker_tests:
 	docker build --pull -f Dockerfile.ci . -t gcp_ci && \
 	docker run -v $$(pwd):/go-control-plane $$(tty -s && echo "-it" || echo) gcp_ci /bin/bash -c /go-control-plane/build/do_ci.sh
-
-docker_benchmarks:
-	docker build --pull -f Dockerfile.ci . -t gcp_ci && \
-	docker run -v $$(pwd):/go-control-plane $$(tty -s && echo "-it" || echo) gcp_ci /bin/bash -c /go-control-plane/build/do_benchmarks.sh

benchmarks/README.md

@@ -0,0 +1,55 @@
+# Benchmarks
+
+These benchmarks are designed to run off the integration test suite, and provide detailed profiling artifacts generated with pprof.
+
+## Prerequisites
+- [Go 1.16+](https://golang.org/dl/)
+- [Graphviz](https://graphviz.org/download/)
+- [pprof](https://github.com/google/pprof)
+- [Docker](https://www.docker.com/)
+
+## Running Locally
+
+To run the benchmarks locally, we take a similar apprach to the integration tests.
+
+### Requirements
+
+* Envoy binary `envoy` available: set `ENVOY` environment variable to the
+  location of the binary, or use the default value `/usr/local/bin/envoy`
+* `go-control-plane` builds successfully
+* Local installation of pprof and graphviz for profiler output
+
+### Steps
+
+To run the benchmark:
+```
+make benchmark MODE=0
+```
+
+There are 5 different modes all corresponding to various profiling outputs:
+```go
+const (
+	PPROF_CPU int = iota
+	PPROF_HEAP
+	PPROF_MUTEX
+	PPROF_BLOCK
+	PPROF_GOROUTINE
+)
+```
+To specifiy the mode, use `MODE` environment variable that corresponds to the output you wish to evaluate.
+
+## Running With Docker
+
+To run the benchmarks, we just require the prerequisite of docker and go.
+
+### Steps
+
+To run the benchmarks:
+
+```
+make docker_benchmarks
+```
+
+This will generate all profile artifacts in the `./benchmarks/reports`. Graphical profile anaylsis is located in `/.benchmarks/pngs`.
+
+For more information on how to interpret these reports/graphs, [click here](https://github.com/google/pprof/blob/master/doc/README.md#graphical-reports)

go.mod

@@ -8,7 +8,7 @@ require (
 	github.com/envoyproxy/protoc-gen-validate v0.1.0
 	github.com/golang/protobuf v1.4.3
 	github.com/google/go-cmp v0.5.0
-	github.com/pkg/profile v1.6.0 // indirect
+	github.com/pkg/profile v1.6.0
 	github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4
 	github.com/stretchr/testify v1.7.0
 	go.opentelemetry.io/proto/otlp v0.7.0

pkg/test/main/README.md

@@ -37,18 +37,3 @@ eventually converges to use the latest pushed configuration) for each run.
 
 You can run ```bin/test -help``` to get a list of the cli flags that
 the test program accepts.  There are also comments in ```main.go```.
-
-## Using the pprof profiler
-
-One customization is to run the go language profiler [pprof](https://github.com/DataDog/go-profiler-notes/blob/main/pprof.md). See also <https://golang.org/pkg/runtime/pprof/>.
-
-The profiler is normally off because it adds overhead to the tests. You can turn 
-it on with the command line option `--pprof`. There is an environment variable 
-`PPROF` for the `make` commands shown above. For example:
-
-    (export PPROF=true; make integration.xds)
-
-The test will then write files of the form `block_profile_xds.pb.gz`. The files
-get written to the root of the project, in the same place as the envoy logs.
-
-You can use `go tool pprof bin/test <file name>` to analyze the profile data.