README.md
1panicparse
2==========
3
4Parses panic stack traces, densifies and deduplicates goroutines with similar
5stack traces. Helps debugging crashes and deadlocks in heavily parallelized
6process.
7
8[](https://travis-ci.org/maruel/panicparse)
9
10panicparse helps make sense of Go crash dumps:
11
12
13
14
15Features
16--------
17
18 * >50% more compact output than original stack dump yet more readable.
19 * Exported symbols are bold, private symbols are darker.
20 * Stdlib is green, main is yellow, rest is red.
21 * Deduplicates redundant goroutine stacks. Useful for large server crashes.
22 * Arguments as pointer IDs instead of raw pointer values.
23 * Pushes stdlib-only stacks at the bottom to help focus on important code.
24 * Usable as a library!
25 [](https://godoc.org/github.com/maruel/panicparse/stack)
26 * Warning: please pin the version (e.g. vendor it). Breaking changes are
27 not planned but may happen.
28 * Parses the source files if available to augment the output.
29 * Works on Windows.
30
31
32Installation
33------------
34
35 go get github.com/maruel/panicparse/cmd/pp
36
37
38Usage
39-----
40
41### Piping a stack trace from another process
42
43#### TL;DR
44
45 * Ubuntu (bash v4 or zsh): `|&`
46 * OSX, [install bash 4+](README.md#updating-bash-on-osx), then: `|&`
47 * Windows _or_ OSX with stock bash v3: `2>&1 |`
48 * [Fish](http://fishshell.com/) shell: `^|`
49
50
51#### Longer version
52
53`pp` streams its stdin to stdout as long as it doesn't detect any panic.
54`panic()` and Go's native deadlock detector [print to
55stderr](https://golang.org/src/runtime/panic1.go) via the native [`print()`
56function](https://golang.org/pkg/builtin/#print).
57
58
59**Bash v4** or **zsh**: `|&` tells the shell to redirect stderr to stdout,
60it's an alias for `2>&1 |` ([bash
61v4](https://www.gnu.org/software/bash/manual/bash.html#Pipelines),
62[zsh](http://zsh.sourceforge.net/Doc/Release/Shell-Grammar.html#Simple-Commands-_0026-Pipelines)):
63
64 go test -v |&pp
65
66
67**Windows or OSX native bash** [(which is
683.2.57)](http://meta.ath0.com/2012/02/05/apples-great-gpl-purge/): They don't
69have this shortcut, so use the long form:
70
71 go test -v 2>&1 | pp
72
73
74**Fish**: It uses [^ for stderr
75redirection](http://fishshell.com/docs/current/tutorial.html#tut_pipes_and_redirections)
76so the shortcut is `^|`:
77
78 go test -v ^|pp
79
80
81**PowerShell**: [It has broken `2>&1` redirection](https://connect.microsoft.com/PowerShell/feedback/details/765551/in-powershell-v3-you-cant-redirect-stderr-to-stdout-without-generating-error-records). The workaround is to shell out to cmd.exe. :(
82
83
84### Investigate deadlock
85
86On POSIX, use `Ctrl-\` to send SIGQUIT to your process, `pp` will ignore
87the signal and will parse the stack trace.
88
89
90### Parsing from a file
91
92To dump to a file then parse, pass the file path of a stack trace
93
94 go test 2> stack.txt
95 pp stack.txt
96
97
98Tips
99----
100
101### GOTRACEBACK
102
103Starting with Go 1.6, [`GOTRACEBACK`](https://golang.org/pkg/runtime/) defaults
104to `single` instead of `all` / `1` that was used in 1.5 and before. To get all
105goroutines trace and not just the crashing one, set the environment variable:
106
107 export GOTRACEBACK=all
108
109or `set GOTRACEBACK=all` on Windows. Probably worth to put it in your `.bashrc`.
110
111
112### Updating bash on OSX
113
114Install bash v4+ on OSX via [homebrew](http://brew.sh) or
115[macports](https://www.macports.org/). Your future self will appreciate having
116done that.
117
118
119### If you have `/usr/bin/pp` installed
120
121You may have the Perl PAR Packager installed. Use long name `panicparse` then;
122
123 go get github.com/maruel/panicparse
124
){kind=link}
){kind=link}