How-to enable trace for a Terraform Enterprise or Terraform Cloud Agent

Introduction

Enabling trace-level logging for a Terraform Enterprise or HCP Terraform agent increases log verbosity, which can help you troubleshoot issues and identify root causes of errors. You may need to enable this mode to gather detailed logs for analysis.

Since the agent can operate in a container or as a native binary, this guide covers the procedure for both environments.

Procedure

Follow the method that matches your agent's deployment environment.

Method 1: Docker Agent

To enable trace logging for an agent running in a Docker container, you must add an environment variable to the docker run command.

1. Add the -e TFC_AGENT_LOG_LEVEL=TRACE flag to your docker run command. The command should be similar to the following example.

   $ docker run -d --name=tfc-agent \
     -e TFC_AGENT_LOG_LEVEL=TRACE \
     -e TFC_AGENT_TOKEN \
     -e TFC_AGENT_NAME \
     hashicorp/tfc-agent:latest

2. Verify that the agent is in debug mode by checking the logs. The log entries should contain a [DEBUG] flag.

   $ docker logs tfc-agent

   Example output:

   ##...
   2022-08-19T11:43:48.590Z [INFO] agent: Starting: version=1.3.0
   2022-08-19T11:43:48.590Z [DEBUG] plugin: starting plugin: path=/home/tfc-agent/bin/tfc-agent-core args=[/home/tfc-agent/bin/tfc-agent-core]
   2022-08-19T11:43:48.590Z [DEBUG] plugin: plugin started: path=/home/tfc-agent/bin/tfc-agent-core pid=12
   ##...

3. To collect the logs into a file, redirect the output of the docker logs command.

   $ docker logs tfc-agent > agent-log

Method 2: Native Binary Agent

To enable trace logging for an agent running as a native binary process, you must set an environment variable before starting the agent.

1. Set the TFC_AGENT_LOG_LEVEL environment variable to TRACE.

   $ export TFC_AGENT_LOG_LEVEL=TRACE

2. Start the agent binary. The trace logs will be written to your terminal for capture.

   $ ./tfc-agent

   Example output:

   ##...
   2023-02-01T21:36:58.677Z [INFO] agent: Starting: version=1.6.0
   2023-02-01T21:36:58.678Z [DEBUG] plugin: starting plugin: path=/root/tfc-agents/tfc-agent-core args=["/root/tfc-agents/tfc-agent-core"]
   2023-02-01T21:36:58.678Z [DEBUG] plugin: plugin started: path=/root/tfc-agents/tfc-agent-core pid=1842538
   2023-02-01T21:36:58.678Z [DEBUG] plugin: waiting for RPC address: path=/root/tfc-agents/tfc-agent-core
   ##...

3. After you reproduce the issue and capture the logs, you can disable trace logging by unsetting the environment variable or starting a new shell session.