From 209b69197179ac427981c64f1d89e21d43a542d7 Mon Sep 17 00:00:00 2001 From: Paul Hinze Date: Fri, 18 Mar 2016 18:05:59 -0500 Subject: [PATCH] docs: Add a section to Debugging docs about crash logs Not necessary for the average user, but perhaps helpful to the intrepid one! --- .../source/docs/internals/debugging.html.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/website/source/docs/internals/debugging.html.md b/website/source/docs/internals/debugging.html.md index b4d2afbd3..cd50edf5e 100644 --- a/website/source/docs/internals/debugging.html.md +++ b/website/source/docs/internals/debugging.html.md @@ -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. + + + +## 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 +log. + +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 +github.com/hashicorp/terraform/builtin/providers/aws.resourceAwsSomeResourceCreate(...) + /opt/gopath/src/github.com/hashicorp/terraform/builtin/providers/aws/resource_aws_some_resource.go:123 +0x123 +github.com/hashicorp/terraform/helper/schema.(*Resource).Refresh(...) + /opt/gopath/src/github.com/hashicorp/terraform/helper/schema/resource.go:209 +0x123 +github.com/hashicorp/terraform/helper/schema.(*Provider).Refresh(...) + /opt/gopath/src/github.com/hashicorp/terraform/helper/schema/provider.go:187 +0x123 +github.com/hashicorp/terraform/rpc.(*ResourceProviderServer).Refresh(...) + /opt/gopath/src/github.com/hashicorp/terraform/rpc/resource_provider.go:345 +0x6a +reflect.Value.call(...) + /opt/go/src/reflect/value.go:435 +0x120d +reflect.Value.Call(...) + /opt/go/src/reflect/value.go:303 +0xb1 +net/rpc.(*service).call(...) + /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: + +``` +github.com/hashicorp/terraform/builtin/providers/aws.resourceAwsSomeResourceCreate(...) + /opt/gopath/src/github.com/hashicorp/terraform/builtin/providers/aws/resource_aws_some_resource.go:123 +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 +happening.