How to enable logging for Terraform Stacks

How To

Summary

This guide provides instructions for enabling the logging for Terraform Stacks in Terraform Enterprise, HCP Terraform and the Terraform CLI.
Enabling these logs is essential for debugging complex orchestration issues, component dependency errors within a Stack, etc.

Objective

The objective is to capture detailed TRACE logs to troubleshoot failed deployment runs or configuration issues in Terraform Stacks. These logs provide a line-by-line execution history of how Terraform processes .tfcomponent.hcl and .tfdeploy.hcl files.

Environment

HCP Terraform (Any tier with Stacks enabled)
Terraform Enterprise (2.0.0 or later)
Terraform CLI (v1.13.0 or later)

Steps

Method 1: Enable "Debug Logging" via Stack Settings (UI of HCP Terraform / Terraform Enterprise)

This method enables the logging for all operations within the specific Stack, until the setting is disabled.

Navigate to the Stacks page in your HCP Terraform / Terraform Enterprise organization.
Select the specific Stack you wish to debug.
Click on Settings in the left-hand navigation menu, then select General.
Locate the Debugging Mode section.
Toggle the Enable Debugging Mode option to On.
Click Save settings. Subsequent deployment runs will now generate detailed logs.
To download the file, navigate to failed operation -> Inspect run data -> Download plan debug log (or Download apply debug log, depending on operation where Stack failed).
The file in .log (plain-text format) will be downloaded to your machine.
After you finish debugging, uncheck Enable Debugging Mode option and save the changes to disable the logging.

Method 2: Enable via API call (HCP Terraform UI / Terraform Enterprise)

If you are creating or updating a Terraform Stack via API, the logging can be enabled by including the attribute debugging-mode: true in your request payload.

It has a similar effect as the UI method described above - all operations within the specific Stack will have the logging enabled and after reproducing the issue, you can download the logs for further analysis.

Method 3: Enable for Terraform CLI

When using the terraform stacks commands locally, you can enable logging directly in your terminal session.

For Unix, Linux, or macOS:

Set the TF_LOG environment variable to TRACE:
```
$ export TF_LOG="TRACE"
```
Run the desired terraform stacks command you wish to debug. Redirect standard output and standard error to a log file using 2>&1 and disable ANSI color escape sequences with the -no-color flag:
```
$ terraform stacks deployment-run approve-all-plans -deployment-run-id <id> -no-color 2>&1 | tee output.log
```
After you finish the debugging, unset the variable:
```
$ unset TF_LOG
```

For Windows (PowerShell):

Set the TF_LOG environment variable to TRACE:
```
$Env:TF_LOG="TRACE"
```
Run the desired terraform stacks command you wish to debug. Redirect standard output and standard error to a log file using 2>&1 and disable ANSI color escape sequences with the -no-color flag:
```
$ terraform stacks deployment-run approve-all-plans -deployment-run-id <id> -no-color 2>&1 | Tee-Object -FilePath output.log
```
After you finish the debugging, unset the variable:
```
$Env:TF_LOG=""
```

Additional Information

Terraform Stacks

Stack API reference

Available CLI commands

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSGH5YK","label":"IBM Terraform Self-Managed"},"ARM Category":[{"code":"a8mgJ0000000DwXQAU","label":"Terraform-\u003EStacks"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"and future releases;2.0.0"}]

Tips