docs: Add a section to Debugging docs about crash logs #5726

merged 1 commit into from Mar 18, 2016
Jump to file or symbol
Failed to load files and symbols.
+62 −0
Diff settings


Just for now

docs: Add a section to Debugging docs about crash logs

Not necessary for the average user, but perhaps helpful to the intrepid
  • Loading branch information...
phinze committed Mar 18, 2016
commit 209b69197179ac427981c64f1d89e21d43a542d7
@@ -15,3 +15,65 @@ You can set `TF_LOG` to one of the log levels `TRACE`, `DEBUG`, `INFO`, `WARN` o
To persist logged output you can set `TF_LOG_PATH` in order to force the log to always go to a specific file when logging is enabled. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled.
If you find a bug with Terraform, please include the detailed log by using a service such as gist.
+<a id="interpreting-a-crash-log"></a>
+## Interpreting a Crash Log
+If Terraform ever crashes (a "panic" in the Go runtime), it saves a log file
+with the debug logs from the session as well as the panic message and backtrace
+to `crash.log`. Generally speaking, this log file is meant to be passed along
+to the developers via a GitHub Issue. As a user, you're not required to dig
+into this file.
+However, if you are interested in figuring out what might have gone wrong
+before filing an issue, here are the the basic details of how to read a crash
+The most interesting part of a crash log is the panic message itself and the
+backtrace immediately following. So the first thing to do is to search the file
+for `panic: `, which should jump you right to this message. It will look
+something like this:
+panic: runtime error: invalid memory address or nil pointer dereference
+goroutine 123 [running]:
+panic(0xabc100, 0xd93000a0a0)
+ /opt/go/src/runtime/panic.go:464 +0x3e6
+ /opt/gopath/src/ +0x123*Resource).Refresh(...)
+ /opt/gopath/src/ +0x123*Provider).Refresh(...)
+ /opt/gopath/src/ +0x123*ResourceProviderServer).Refresh(...)
+ /opt/gopath/src/ +0x6a
+ /opt/go/src/reflect/value.go:435 +0x120d
+ /opt/go/src/reflect/value.go:303 +0xb1
+ /opt/go/src/net/rpc/server.go:383 +0x1c2
+created by net/rpc.(*Server).ServeCodec
+ /opt/go/src/net/rpc/server.go:477 +0x49d
+The key part of this message is the first two lines that involve `hashicorp/terraform`. In this example:
+ /opt/gopath/src/ +0x123
+The first line tells us that the method that failed is
+`resourceAwsSomeResourceCreate`, which we can deduce that involves the creation
+of a (fictional) `aws_some_resource`.
+The second line points to the exact line of code that caused the panic,
+which--combined with the panic message itself--is normally enough for a
+developer to quickly figure out the cause of the issue.
+As a user, this information can help work around the problem in a pinch, since
+it should hopefully point to the area of the code base in which the crash is