From 0b10ed4d88b43d76f7252ae6f139bf29d3ececa5 Mon Sep 17 00:00:00 2001 From: Hidde Beydals Date: Mon, 8 Feb 2021 10:08:35 +0100 Subject: [PATCH 1/3] Add guide for pprof endpoints Signed-off-by: Hidde Beydals --- docs/dev-guides/debugging.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/dev-guides/debugging.md diff --git a/docs/dev-guides/debugging.md b/docs/dev-guides/debugging.md new file mode 100644 index 00000000..870ef224 --- /dev/null +++ b/docs/dev-guides/debugging.md @@ -0,0 +1,35 @@ +# Advanced debugging + +This guide covers more advanced debugging topics such as collecting +runtime profiling data from GitOps Toolkit components. + +As a user, this page normally should be a last resort, but you may +be asked by a maintainer to share a [collected profile](#collecting-a-profile) +to debug e.g. performance issues. + +## Pprof + +The [GitOps Toolkit components](../components/index.md) serve [`pprof`](https://golang.org/pkg/net/http/pprof/) +runtime profiling data on their metrics HTTP server (default `:8080`). + +### Endpoints + +| Endpoint | Path | +|-------------|------------------------| +| Index | `/debug/pprof/` | +| CPU profile | `/debug/pprof/profile` | +| Symbol | `/debug/pprof/symbol` | +| Trace | `/debug/pprof/trace` | + +### Collecting a profile + +To collect a profile, port-forward to the component's metrics endpoint and +collect the data from the [endpoint](#endpoints) of choice: + +```console +$ kubectl port-forward -n deploy/ 8080 +$ curl -Sk -v http://localhost:8080/debug/pprof/heap > heap.out +``` + +The collected profile [can be analyzed using `go`](https://blog.golang.org/pprof), +or shared with one of the maintainers. From 1378530aebcfbf7d861f9904f440c6dc13644f7e Mon Sep 17 00:00:00 2001 From: Hidde Beydals Date: Mon, 8 Feb 2021 10:37:32 +0100 Subject: [PATCH 2/3] Add section about resource usage Signed-off-by: Hidde Beydals --- docs/dev-guides/debugging.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/dev-guides/debugging.md b/docs/dev-guides/debugging.md index 870ef224..b0b125cc 100644 --- a/docs/dev-guides/debugging.md +++ b/docs/dev-guides/debugging.md @@ -23,8 +23,8 @@ runtime profiling data on their metrics HTTP server (default `:8080`). ### Collecting a profile -To collect a profile, port-forward to the component's metrics endpoint and -collect the data from the [endpoint](#endpoints) of choice: +To collect a profile, port-forward to the component's metrics endpoint +and collect the data from the [endpoint](#endpoints) of choice: ```console $ kubectl port-forward -n deploy/ 8080 @@ -33,3 +33,10 @@ $ curl -Sk -v http://localhost:8080/debug/pprof/heap > heap.out The collected profile [can be analyzed using `go`](https://blog.golang.org/pprof), or shared with one of the maintainers. + +## Resource usage + +As `kubectl top` gives a limited (and at times inaccurate) overview of +resource usage, it is often better to make use of the Grafana metrics +to gather insights. See [monitoring](../guides/monitoring.md) for a +guide on how to visualize this data with a Grafana dashboard. From 217574b75ce28f2384fadfa89773d78e08d30c71 Mon Sep 17 00:00:00 2001 From: Hidde Beydals Date: Mon, 8 Feb 2021 11:40:47 +0100 Subject: [PATCH 3/3] Add debugging to dev guides menu Signed-off-by: Hidde Beydals --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 6087e4f9..900c0f45 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -196,6 +196,7 @@ nav: - Uninstall: cmd/flux_uninstall.md - Dev Guides: - Watching for source changes: dev-guides/source-watcher.md + - Advanced debugging: dev-guides/debugging.md - Roadmap: roadmap/index.md - Contributing: contributing/index.md - FAQ: faq/index.md