Skip to content

Diagnostics & Logging

Global flags, adopted from sq, control verbose output, file logging, error rendering, and profiling.

They are cross-cutting concerns handled at the CLI boundary. They never change query results.

Flags

flag default effect
-v, --verbose off print diagnostics (source resolved, store opened, query complete with scan count and elapsed) to stderr, plus the query plan and a live backend command trace (disables the progress spinner)
--log off enable logging to a file (also via IQ_LOG)
--log.file <user cache dir>/iq/iq.log log file path. An empty value disables logging
--log.level DEBUG DEBUG, INFO, WARN, or ERROR
--log.format text text or json
--error.format text error output format: text or json
--error.stack off print the wrapped error cause chain to stderr (can include backend internals, credentials stay redacted)
--no-progress off disable the scan progress spinner (-v disables it too). See Global flags
--error.format.text.verbose on for a jq syntax error in text format, draw a caret span under the offending token
--debug.pprof off write a runtime profile of the whole run: cpu, mem, block, mutex, goroutine, thread, or trace

marks a flag every iq command accepts (see Global flags).

Logging

The --log* flags also read the environment when the flag is not set. The precedence is flag > env > default. The environment variables are IQ_LOG, IQ_LOG_FILE, IQ_LOG_LEVEL, IQ_LOG_FORMAT.

--log writes structured records to a file (down to the chosen level, always plain, never tinted).

iq removes the connection password from each log record before it writes the record to the file or to the -v stream. This applies to the source location, to the message, and to each error, also when the URI does not parse. The error that iq prints on stderr gets the same redaction. iq does not filter other record data, for example query text and returned values.

Verbose

-v writes a terse human stream to stderr (INFO and above). The stream is tinted when stderr is a terminal. It follows the same -M/-C/NO_COLOR decision as colored output.

Examples

Verbose diagnostics on stderr
./iq -v '.[]'
Structured logs to a file
./iq --log --log.file=/tmp/iq.log --log.format=json '.[]'
Enable logging via the environment
IQ_LOG=true IQ_LOG_FILE=/tmp/iq.log ./iq '.[]'
Machine-readable errors
./iq --error.format=json '.bad |'
Runtime profile
./iq --debug.pprof=cpu '.[]' && go tool pprof cpu.pprof