> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/logging/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Logging

Itential Gateway 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**

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

```bash
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 in Gateway

### 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`.

```bash
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:

```bash
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:

```json
{"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

Gateway 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

Gateway 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.