How to Enable TRACE Logging for the Terraform Cloud Agent on Kubernetes/OpenShift

Introduction

When a run is started in a workspace using Terraform Enterprise, a pod is launched with the default agent to execute the Terraform code.

If execution issues or errors occur, you may need more detailed logging from the agent to assist with troubleshooting. This can be achieved by enabling TRACE-level logging as documented here

To enable this, the agent must start with the environment variable:

TFC_AGENT_LOG_LEVEL=TRACE

Prerequisites

• Terraform Enterprise deployed via Helm

• Workspaces configured to use the default remote execution mode

• Access to modify the Terraform Enterprise Helm overrides.yaml

Solution

• Update the overrides.yaml file used in your Terraform Enterprise Helm deployment to include the TRACE log level for the agent worker pod.

• Add or modify the following section:

agentWorkerPodTemplate:
  spec:
    containers:
      - env:
          - name: TFC_AGENT_LOG_LEVEL
            value: TRACE

• Start a new workspace run. The agent logs should now include TRACE-level output similar to the following:

2026-02-25T11:50:38.970Z [INFO]  agent: Starting: agent_version=1.25.1 os=linux arch=arm64
2026-02-25T11:50:38.970Z [DEBUG] plugin: starting plugin: path=/home/tfc-agent/bin/tfc-agent-core args=["/home/tfc-agent/bin/tfc-agent-core"]
2026-02-25T11:50:38.971Z [DEBUG] plugin: plugin started: path=/home/tfc-agent/bin/tfc-agent-core pid=13
2026-02-25T11:50:38.971Z [DEBUG] plugin: waiting for RPC address: plugin=/home/tfc-agent/bin/tfc-agent-core
2026-02-25T11:50:38.981Z [DEBUG] plugin: using plugin: version=1
2026-02-25T11:50:38.981Z [DEBUG] plugin.tfc-agent-core: plugin address: address=/tmp/plugin4123805033 network=unix timestamp=2026-02-25T11:50:38.981Z
2026-02-25T11:50:38.982Z [INFO]  core: Starting: version=1.25.1
2026-02-25T11:50:38.982Z [DEBUG] core: Registering agent...

Additional Information

• Official documentation for the agent log level can be found here