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

Avatar
Darrell F. Williams
  • Updated

Use Case

Enabling trace for the Terraform Enterprise (TFE) or Terraform Cloud (TFC) agent will increase the verbosity within the logs which helps troubleshoot and identify root causes or potential errors. 

Upon request from a support engineer, the workflow would consist of placing the agent in trace, reproducing the issue then supplying the debug logs. 

Since the TFE or TFC agent can operate in two different environments, in a container such as Docker or binary execution, this article will cover how to enable trace in both methods. 

Procedure

Docker Agent

The process for enabling trace for the agent that is running in a Docker container is as follows:   

  • Add -e TFC_AGENT_LOG_LEVEL=TRACEto the Docker run syntax.  The command should be arranged similarly to this:
docker run -d --name=tfc-agent -e TFC_AGENT_LOG_LEVEL=TRACE -e TFC_AGENT_TOKEN -e TFC_AGENT_NAME hashicorp/tfc-agent:latest
  • You can then check the logs by using the command docker logs tfc-agentand your logs should contain a [DEBUG] flag. This means that the TFC Agent is launched in debug mode and it will contain detailed logs. 
    • To simplify log collection for attachment to a support ticket, you can run docker logs tfc-agent > agent-log , download the agent-log  file and upload it with your ticket.
For example:

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

Native Binary Agent

The process for enabling trace in an agent running as a binary process requires setting an environment variable:

export TFC_AGENT_LOG_LEVEL=TRACE
  • Start up the agent binary for example ./tfc-agent and the race log will be written to the terminal for capture.  
For example: 

root@LinuxVM:~/tfc-agents# ./tfc-agent &
[1] 1842530
root@ip-10-0-106-175:~/tfc-agents# 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
2023-02-01T21:36:58.688Z [DEBUG] plugin: using plugin: version=1
2023-02-01T21:36:58.688Z [DEBUG] plugin.tfc-agent-core: plugin address: address=/tmp/plugin2384625704 network=unix timestamp=2023-02-01T21:36:58.688Z
2023-02-01T21:36:58.691Z [INFO]  core: Starting: version=1.6.0
2023-02-01T21:36:58.691Z [DEBUG] core: Registering agent...
2023-02-01T21:36:58.691Z [DEBUG] core: Executing HTTP request: attempt=0 method=POST url=https://app.terraform.io/api/agent/register
  •   Once the issue has been reproduced, capture the debug logs and provide them upon request. After this has been conducted you can disable the trace.  

Additional Information

Articles in this section

See more

Related articles