diff --git a/docs/PROFILING.md b/docs/PROFILING.md new file mode 100644 index 000000000..9184d1b13 --- /dev/null +++ b/docs/PROFILING.md @@ -0,0 +1,79 @@ +# Profiling Dendrite + +If you are running into problems with Dendrite using excessive resources (e.g. CPU or RAM) then you can use the profiler to work out what is happening. + +Dendrite contains an embedded profiler called `pprof`, which is a part of the standard Go toolchain. + +### Enable the profiler + +To enable the profiler, start Dendrite with the `PPROFLISTEN` environment variable. This variable specifies which address and port to listen on, e.g. + +``` +PPROFLISTEN=localhost:65432 ./bin/dendrite-monolith-server ... +``` + +If pprof has been enabled successfully, a log line at startup will show that pprof is listening: + +``` +WARN[2020-12-03T13:32:33.669405000Z] [/Users/neilalexander/Desktop/dendrite/internal/log.go:87] SetupPprof + Starting pprof on localhost:65432 +``` + +### Profiling CPU usage + +To examine where CPU time is going, you can call the `profile` endpoint: + +``` +http://localhost:65432/debug/pprof/profile?seconds=30 +``` + +The profile will run for the specified number of `seconds` and then will produce a result. + +If you have Go installed and want to explore the profile, you can invoke `go tool pprof` to start the profile directly. The `-http=` parameter will instruct `go tool pprof` to start a web server providing a view of the captured profile: + +``` +go tool pprof -http=localhost:23456 http://localhost:65432/debug/pprof/profile?seconds=30 +``` + +You can then visit `http://localhost:23456` in your web browser to see a visual representation of the profile. Particularly usefully, in the "View" menu, you can select "Flame Graph" to see a proportional interactive graph of CPU usage. + +If you don't have the Go tools installed but just want to capture the profile to send to someone else, you can instead use `curl` to download the profiler results: + +``` +curl -O http://localhost:65432/debug/pprof/profile?seconds=30 +``` + +This will block for the specified number of seconds, capturing information about what Dendrite is doing, and then produces a `profile` file, which you can send onward. + +### Profiling memory usage + +To examine where memory usage is going, you can call the `heap` endpoint: + +``` +http://localhost:65432/debug/pprof/heap +``` + +The profile will return almost instantly. + +If you have Go installed and want to explore the profile, you can invoke `go tool pprof` to start the profile directly. The `-http=` parameter will instruct `go tool pprof` to start a web server providing a view of the captured profile: + +``` +go tool pprof -http=localhost:23456 http://localhost:65432/debug/pprof/heap +``` + +You can then visit `http://localhost:23456` in your web browser to see a visual representation of the profile. The "Sample" menu lets you select between four different memory profiles: + +* `inuse_space`: Shows how much actual heap memory is allocated per function (this is generally the most useful profile when diagnosing high memory usage) +* `inuse_objects`: Shows how many heap objects are allocated per function +* `alloc_space`: Shows how much memory has been allocated per function (although that memory may have since been deallocated) +* `alloc_objects`: Shows how many allocations have been made per function (although that memory may have since been deallocated) + +Also in the "View" menu, you can select "Flame Graph" to see a proportional interactive graph of the memory usage. + +If you don't have the Go tools installed but just want to capture the profile to send to someone else, you can instead use `curl` to download the profiler results: + +``` +curl -O http://localhost:65432/debug/pprof/heap +`` + +This will almost instantly produce a `heap` file, which you can send onward.