Skip to main content

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

OptionDescription
--log-level <level>Change log config level to specified level.
--verboseChange 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

LevelColorDescription
tracebackground greenDetailed information about internal process status.
e.g. internal process status.
debuggreenDiagnostic information that is helpful for troubleshooting or testing.
e.g. detailed progress (nth record processing, ),
infoblueInformation that is helpful for users in normal usage.
e.g. progress
warnyellowThe process can continue, but a potential problem happens.
e.g. exported/imported records are empty
errorredThe process is aborting due to an error.
e.g. Authentication failure, API limitation, wrong inputs
fatalbackground redThe 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 levelConfig level
tracedebuginfowarnerrorfatalnone
traceincludedexcludedexcludedexcludedexcludedexcludedexcluded
debugincludedincludedexcludedexcludedexcludedexcludedexcluded
infoincludedincludedincludedexcludedexcludedexcludedexcluded
warnincludedincludedincludedincludedexcludedexcludedexcluded
errorincludedincludedincludedincludedincludedexcludedexcluded
fatalincludedincludedincludedincludedincludedincludedexcluded