Debugging

Inevitably, you will need to troubleshoot scripts running in gateway. As such, logging tools are provided to support debugging.

View Logs

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

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 whichever command you are running. For example, running iagctl get services --verbose will launch the gateway with console logs.

File Logs

In most cases, the gateway log file will be 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 will be located at GATEWAY_LOG_SERVER_DIR/gateway.log.

>_ iagctl server`/`>_ iagctl runner

If the GATEWAY_LOG_SERVER_DIR location is not specified, a default location of /var/log/gateway/gateway.log will be used.

Log Format

By default, logs are displayed in the format shown below:

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

If you prefer to have logs displayed in JSON format, set the environment variables GATEWAY_LOG_FILE_JSON=true or GATEWAY_LOG_CONSOLE_JSON=true. Some clients may prefer JSON to more easily feed output logs into third-party software such as log aggregation programs.

JSON logs will resemble the format shown below:

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

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

Log Levels

The gateway supports many 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 used by gateway.
• The default value of GATEWAY_LOG_LEVEL is INFO.
• Both file and console logs will 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

The gateway will display 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.