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.