Debugging

  • Published on Jul 15, 2025
Prev Next

Itential Automation Gateway IAG provides the following logging tools to support your debugging efforts.

View Logs

To quickly view logs, set GATEWAY_LOG_LEVEL = DEBUG and run all iagctl commands with the --verbose flag.

Example

export GATEWAY_LOG_LEVEL="DEBUG"
iagctl get services --verbose

iagctl get services
NAME      TYPE            CREATED
ha2-iap   opentofu-plan   2024-08-20T17:45:01Z
ha3       opentofu-plan   2024-08-20T21:00:19Z

export GATEWAY_LOG_LEVEL="DEBUG"
iagctl get services --verbose
2024-08-29T17:36:17Z INF writing logs to /Users/gateway/.gateway.d/gateway.log
2024-08-29T17:36:17Z INF using configuration file at /Users/gateway/.gateway.d/gateway.conf
2024-08-29T17:36:17Z INF using local store database file at gateway.db
2024-08-29T17:36:18Z INF using local resources as application mode is set to local
2024-08-29T17:36:18Z DBG Getting store's values for prefix 'iagctl/bullpen/services/v1'
2024-08-29T17:36:18Z DBG Getting store's values for prefix 'iagctl/bullpen/decorator/v1'

NAME      TYPE            CREATED
ha2-iap   opentofu-plan   2024-08-20T17:45:01Z
ha3       opentofu-plan   2024-08-20T21:00:19Z

Logging

Console Logs

To display console logs to the terminal, append --verbose to the command you are running. For example, running iagctl get services --verbose launches the gateway with console logs.

File Logs

In most cases, the gateway log file is located at GATEWAY_APPLICATION_WORKING_DIR/gateway.log. This location is used when users run CLI commands to accommodate gateway CLI users that do not have /var/log access.

When gateway is launched as a server or runner, the log file is located at GATEWAY_LOG_SERVER_DIR/gateway.log.

iagctl server`/`>_ iagctl runner

If the GATEWAY_LOG_SERVER_DIR location is not specified, the system uses the default location /var/log/gateway/gateway.log.

Log Format

By default, logs are displayed in the following format:

2024-02-14T09:18:28-06:00 INF grpc server is starting up

You can display logs in JSON format by setting the environment variables GATEWAY_LOG_FILE_JSON=true or GATEWAY_LOG_CONSOLE_JSON=true. JSON format allows easier integration with third-party software such as log aggregation programs.

JSON logs resemble the following format:

{"level":"info","time":"2024-02-14T09:18:28-06:00","message":"grpc server is starting up"}

By default, console logs have color formatting. To remove the color, set the environment variable GATEWAY_TERMINAL_NO_COLOR=true.

Log Levels

IAG supports different logging levels to denote the importance of a log as well as the severity of an error.

  • Use the GATEWAY_LOG_LEVEL environment variable to set the log level
  • The default value of GATEWAY_LOG_LEVEL is INFO
  • Both file and console logs match the value set by GATEWAY_LOG_LEVEL

Supported logging levels (ordered from least to most important) include:

  • TRACE
  • DEBUG
  • INFO
  • WARN
  • ERROR
  • FATAL
  • DISABLED

IAG displays logs for the level set in GATEWAY_LOG_LEVEL as well as any logs of higher importance.

For example, if INFO logs are selected, a user will be shown logs for INFO, WARN, ERROR, and FATAL. They will not see DEBUG and TRACE logs.