github.com/adrian-bl/terraform@v0.7.0-rc2.0.20160705220747-de0a34fc3517/website/source/docs/internals/debugging.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Debugging"
     4  sidebar_current: "docs-internals-debug"
     5  description: |-
     6    Terraform has detailed logs which can be enabled by setting the TF_LOG environmental variable to any value. This will cause detailed logs to appear on stderr
     7  ---
     8  
     9  # Debugging Terraform
    10  
    11  Terraform has detailed logs which can be enabled by setting the `TF_LOG` environmental variable to any value. This will cause detailed logs to appear on stderr.
    12  
    13  You can set `TF_LOG` to one of the log levels `TRACE`, `DEBUG`, `INFO`, `WARN` or `ERROR` to change the verbosity of the logs. `TRACE` is the most verbose and it is the default if `TF_LOG` is set to something other than a log level name.
    14  
    15  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.
    16  
    17  If you find a bug with Terraform, please include the detailed log by using a service such as gist.
    18  
    19  <a id="interpreting-a-crash-log"></a>
    20  
    21  ## Interpreting a Crash Log
    22  
    23  If Terraform ever crashes (a "panic" in the Go runtime), it saves a log file
    24  with the debug logs from the session as well as the panic message and backtrace
    25  to `crash.log`. Generally speaking, this log file is meant to be passed along
    26  to the developers via a GitHub Issue. As a user, you're not required to dig
    27  into this file.
    28  
    29  However, if you are interested in figuring out what might have gone wrong
    30  before filing an issue, here are the the basic details of how to read a crash
    31  log.
    32  
    33  The most interesting part of a crash log is the panic message itself and the
    34  backtrace immediately following. So the first thing to do is to search the file
    35  for `panic: `, which should jump you right to this message. It will look
    36  something like this:
    37  
    38  ```
    39  panic: runtime error: invalid memory address or nil pointer dereference
    40  
    41  goroutine 123 [running]:
    42  panic(0xabc100, 0xd93000a0a0)
    43  	/opt/go/src/runtime/panic.go:464 +0x3e6
    44  github.com/hashicorp/terraform/builtin/providers/aws.resourceAwsSomeResourceCreate(...)
    45  	/opt/gopath/src/github.com/hashicorp/terraform/builtin/providers/aws/resource_aws_some_resource.go:123 +0x123
    46  github.com/hashicorp/terraform/helper/schema.(*Resource).Refresh(...)
    47  	/opt/gopath/src/github.com/hashicorp/terraform/helper/schema/resource.go:209 +0x123
    48  github.com/hashicorp/terraform/helper/schema.(*Provider).Refresh(...)
    49  	/opt/gopath/src/github.com/hashicorp/terraform/helper/schema/provider.go:187 +0x123
    50  github.com/hashicorp/terraform/rpc.(*ResourceProviderServer).Refresh(...)
    51  	/opt/gopath/src/github.com/hashicorp/terraform/rpc/resource_provider.go:345 +0x6a
    52  reflect.Value.call(...)
    53  	/opt/go/src/reflect/value.go:435 +0x120d
    54  reflect.Value.Call(...)
    55  	/opt/go/src/reflect/value.go:303 +0xb1
    56  net/rpc.(*service).call(...)
    57  	/opt/go/src/net/rpc/server.go:383 +0x1c2
    58  created by net/rpc.(*Server).ServeCodec
    59  	/opt/go/src/net/rpc/server.go:477 +0x49d
    60  ```
    61  
    62  The key part of this message is the first two lines that involve `hashicorp/terraform`. In this example:
    63  
    64  ```
    65  github.com/hashicorp/terraform/builtin/providers/aws.resourceAwsSomeResourceCreate(...)
    66  	/opt/gopath/src/github.com/hashicorp/terraform/builtin/providers/aws/resource_aws_some_resource.go:123 +0x123
    67  ```
    68  
    69  The first line tells us that the method that failed is
    70  `resourceAwsSomeResourceCreate`, which we can deduce that involves the creation
    71  of a (fictional) `aws_some_resource`.
    72  
    73  The second line points to the exact line of code that caused the panic,
    74  which--combined with the panic message itself--is normally enough for a
    75  developer to quickly figure out the cause of the issue.
    76  
    77  As a user, this information can help work around the problem in a pinch, since
    78  it should hopefully point to the area of the code base in which the crash is
    79  happening.