Logging
Overview
cli-kintone supports various logs that help users to check progress, debug, and report issues.
Users can control log output by command line options.
Command line options
| Option | Description |
|---|---|
--log-level <level> | Change log config level to specified level. |
--verbose | Change log config level to debug |
Log format
[(datetime)] (log level): (message)
- datetime: The datetime string in ISO8601 format. (
YYYY-MM-DDTHH:mm:ss.sssZ) - log level: The log event level. Please see log levels for more details.
- message: The message that describes the event.
On the terminal with color support, the log level is printed with a color.
If a message has line breaks, each line should be shown with a prefix.
# When the error message has line breaks:
# "The first line\nThe second line\nThe third line"
# The message should be printed as follows
[2023-09-14T19:58:55.938Z] ERROR: The first line
[2023-09-14T19:58:55.938Z] ERROR: The second line
[2023-09-14T19:58:55.938Z] ERROR: The third line
Log printing destination
We print all kinds of logs to stderr.
Why: The output of command is printed to stdout, so progress/errors is better to be printed to stderr.
Log levels
We have two types of log levels: log event level and log config level.
- Log event level: How we categorize logs.
- When we send an event message to the logger, each event has a log event level.
- Log config level: How we filter logs to be printed
- When the logger prints logs, the logger will filter logs using the log config level.
Log event level
| Level | Color | Description |
|---|---|---|
| trace | background green | Detailed information about internal process status. e.g. internal process status. |
| debug | green | Diagnostic information that is helpful for troubleshooting or testing. e.g. detailed progress (nth record processing, ), |
| info | blue | Information that is helpful for users in normal usage. e.g. progress |
| warn | yellow | The process can continue, but a potential problem happens. e.g. exported/imported records are empty |
| error | red | The process is aborting due to an error. e.g. Authentication failure, API limitation, wrong inputs |
| fatal | background red | The process is aborting with an unexpected error. e.g. NPE, OOM, unhandled error from libraries |
Log config level
The default log config level is info.
| Event level | Config level | ||||||
|---|---|---|---|---|---|---|---|
| trace | debug | info | warn | error | fatal | none | |
| trace | included | excluded | excluded | excluded | excluded | excluded | excluded |
| debug | included | included | excluded | excluded | excluded | excluded | excluded |
| info | included | included | included | excluded | excluded | excluded | excluded |
| warn | included | included | included | included | excluded | excluded | excluded |
| error | included | included | included | included | included | excluded | excluded |
| fatal | included | included | included | included | included | included | excluded |