From 0dac08a3d24c54c67ffa1df6adab52311dcf72d9 Mon Sep 17 00:00:00 2001 From: Joseph Cook <33655003+jmcook1186@users.noreply.github.com> Date: Fri, 4 Nov 2022 20:48:11 +0000 Subject: [PATCH] docs: update stacktrace info (#26106) * update stacktrace info * add `filter` parameter --- docs/_developers/devguide.md | 80 +++++++++++++++++++++++++++++++++++- 1 file changed, 79 insertions(+), 1 deletion(-) diff --git a/docs/_developers/devguide.md b/docs/_developers/devguide.md index 171016a486..6338631861 100644 --- a/docs/_developers/devguide.md +++ b/docs/_developers/devguide.md @@ -88,6 +88,81 @@ For more information, see the [go test flags][testflag] documentation. ### Getting Stack Traces +A stack trace provides a very detailed look into the current state of the geth node. +It helps us to debug issues easier as it contains information about what is currently +done by the node. Stack traces can be created by running `debug.stacks()` in the Geth +console. If the node was started without the console command or with a script in the +background, the following command can be used to dump the stack trace into a file. + +``` +geth attach --exec "debug.stacks()" > stacktrace.txt +``` +Geth logs the location of the IPC endpoint on startup. It is typically under +`/home/user/.ethereum/geth.ipc` or `/tmp/geth.ipc`. + +`debug.stacks()` also takes an optional `filter` argument. Passing a package name or +filepath to `filter` restricts the output to stack traces involcing only that package/file. +For example: + +```sh +debug.stacks("enode") +``` + +returns data that looks like: + +```terminal +INFO [11-04|16:15:54.486] Expanded filter expression filter=enode expanded="`enode` in Value" +goroutine 121 [chan receive, 3 minutes]: +github.com/ethereum/go-ethereum/p2p/enode.(*FairMix).nextFromAny(...) + github.com/ethereum/go-ethereum/p2p/enode/iter.go:241 +github.com/ethereum/go-ethereum/p2p/enode.(*FairMix).Next(0xc0008c6060) + github.com/ethereum/go-ethereum/p2p/enode/iter.go:215 +0x2c5 +github.com/ethereum/go-ethereum/p2p.(*dialScheduler).readNodes(0xc00021c2c0, {0x18149b0, 0xc0008c6060}) + github.com/ethereum/go-ethereum/p2p/dial.go:321 +0x9f +created by github.com/ethereum/go-ethereum/p2p.newDialScheduler + github.com/ethereum/go-ethereum/p2p/dial.go:179 +0x425 +``` + +and +```sh +debug.stacks("consolecmd.go") +``` + +returns data that looks like: + +```terminal +INFO [11-04|16:16:47.141] Expanded filter expression filter=consolecmd.go expanded="`consolecmd.go` in Value" +goroutine 1 [chan receive]: +github.com/ethereum/go-ethereum/internal/jsre.(*JSRE).Do(0xc0004223c0, 0xc0003c00f0) + github.com/ethereum/go-ethereum/internal/jsre/jsre.go:230 +0xf4 +github.com/ethereum/go-ethereum/internal/jsre.(*JSRE).Evaluate(0xc00033eb60?, {0xc0013c00a0, 0x1e}, {0x180d720?, 0xc000010018}) + github.com/ethereum/go-ethereum/internal/jsre/jsre.go:289 +0xb3 +github.com/ethereum/go-ethereum/console.(*Console).Evaluate(0xc0005366e0, {0xc0013c00a0?, 0x0?}) + github.com/ethereum/go-ethereum/console/console.go:353 +0x6d +github.com/ethereum/go-ethereum/console.(*Console).Interactive(0xc0005366e0) + github.com/ethereum/go-ethereum/console/console.go:481 +0x691 +main.localConsole(0xc00026d580?) + github.com/ethereum/go-ethereum/cmd/geth/consolecmd.go:109 +0x348 +github.com/ethereum/go-ethereum/internal/flags.MigrateGlobalFlags.func2.1(0x20b52c0?) + github.com/ethereum/go-ethereum/internal/flags/helpers.go:91 +0x36 +github.com/urfave/cli/v2.(*Command).Run(0x20b52c0, 0xc000313540) + github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/command.go:177 +0x719 +github.com/urfave/cli/v2.(*App).RunContext(0xc0005501c0, {0x1816128?, 0xc000040110}, {0xc00003c180, 0x3, 0x3}) + github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/app.go:387 +0x1035 +github.com/urfave/cli/v2.(*App).Run(...) + github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/app.go:252 +main.main() + github.com/ethereum/go-ethereum/cmd/geth/main.go:266 +0x47 + +goroutine 159 [chan receive, 4 minutes]: +github.com/ethereum/go-ethereum/node.(*Node).Wait(...) + github.com/ethereum/go-ethereum/node/node.go:529 +main.localConsole.func1() + github.com/ethereum/go-ethereum/cmd/geth/consolecmd.go:103 +0x2d +created by main.localConsole + github.com/ethereum/go-ethereum/cmd/geth/consolecmd.go:102 +0x32e +``` + If `geth` is started with the `--pprof` option, a debugging HTTP server is made available on port 6060. You can bring up to see the heap, running routines etc. By clicking "full goroutine stack dump" you can generate a trace @@ -111,7 +186,10 @@ and have the stacktrace too, you can use the `-QUIT` signal with `kill`: killall -QUIT geth ``` -This will dump stack traces for each instance to their respective log file. +This will dump stack traces for each instance to their respective log file. Please do not +dump the stack trace into a GH issue as it is very hard for reviewers to read and intepret. +It is much better to upload the trace to a Github Gist or Pastebin and put the link in the +issue. [install-guide]: ../install-and-build/installing-geth [code-review]: ../developers/code-review-guidelines