logging.md

Logging

The pipeline library provides an own Logger since pipeline provides only echo step at the moment and is quite communicative.

At the end the Logger also uses the echo step but it filters out messages you don't want to see the whole time.

Table of contents

• Initialization
• Features
  • Colorized output
• LogLevels
• Examples
  • Example 1: Do a trace logging
  • Example 2: Do a warning logging and hide loglevel below
  • Example 3: Log an object
• Configuration options
  • logLevel (optional)
• Related classes

Initialization

In order to work properly the Logger has to be initialized once at the beginning of your pipeline script:

// do the import
import io.wcm.devops.jenkins.pipeline.utils.logging.LogLevel
import io.wcm.devops.jenkins.pipeline.utils.logging.Logger

// initialize the logger with WorkflowScript reference (this)
Logger.init(this, [ logLevel: LogLevel.INFO ])

The logger needs a reference to the DSL instance which is the steps object in a pipeline script

Features

Colorized output

The pipeline library the Logger supports xterm color output. The text remains black but the log level part like [WARN] will echoed using colors.

The colors used are from the 88/256 colors table. :bulb: For more information have a look at https://misc.flogisoft.com/bash/tip_colors_and_formatting

The colorized output is enabled automatically when the ansiColor wrapper is used. :bulb: You can use logs within and without the ansiColor plugin in the same project. The logger detects the wrapper by checking for the TERM environment variable.

LogLevels

The Logger supports the following LogLevels (from priority low to high, log level / color code)

Name	Level (int)	Color
ALL	0	0
TRACE	2	8
DEBUG	3	12
INFO	4	0
DEPRECATED	5	93
WARN	6	202
ERROR	7	5
FATAL	8	9
NONE	Integer.MAX_VALUE	0

If you want to show only INFO and above (e.g. WARN, ERROR or FATAL set the log level to LogLevel.INFO.

If you want the logger to be as communicative as the pipeline is set the LogLevel to ALL.

When you don't want to see any log message at all either do not initialize the Logger or set the LogLevel to NONE

Examples

Example 1: Do a trace logging

// do the import
import io.wcm.devops.jenkins.pipeline.utils.logging.LogLevel
import io.wcm.devops.jenkins.pipeline.utils.logging.Logger

// initialize the logger 
Logger.init(this, [ logLevel: LogLevel.TRACE ])
Logger log = new Logger(this)

log.trace("I am a trace log message")

Output:

[INFO] [ScriptName] : I am a trace log message

Example 2: Do a warning logging and hide loglevel below

// do the import
import io.wcm.devops.jenkins.pipeline.utils.logging.LogLevel
import io.wcm.devops.jenkins.pipeline.utils.logging.Logger
import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

// initialize the logger 
Logger.init(this, [ (LOGLEVEL) : LogLevel.WARN] )
Logger log = new Logger(this)

log.trace("I am a trace log message")
log.warn("I am a warn log message")

Output:

[WARN] [ScriptName] : I am a warn log message

Example 3: Log an object

💡 Logging an object is limited when running in untrusted mode. The Logger may fail to the the class name of the object to be logged, but the String representation (toString()) should always work.

// do the import
import io.wcm.devops.jenkins.pipeline.utils.logging.LogLevel
import io.wcm.devops.jenkins.pipeline.utils.logging.Logger
import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

Map config = [ (LOGLEVEL) : LogLevel.DEBUG ]

// initialize the logger 
Logger.init(this, config)
Logger log = new Logger(this)

log.debug("This is the config: ", config)

Output:

[DEBUG] [ScriptName] : This is the config -> (LinkedHashMap) [logLevel:LogLevel.DEBUG] 

Example 4: Colorized log output

This example will output all log levels with theis colors.

// do the import
import io.wcm.devops.jenkins.pipeline.utils.logging.LogLevel
import io.wcm.devops.jenkins.pipeline.utils.logging.Logger
import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

Map config = [ (LOGLEVEL) : LogLevel.TRACE ]

// initialize the logger 
Logger.init(this, config)
Logger log = new Logger(this)

ansiColor('xterm') {
    log.trace("trace logging")
    log.debug("debug logging")
    log.info("info logging")
    log.deprecated("deprecated logging")
    log.warn("warn logging")
    log.error("error logging")
    log.fatal("fatal logging")    
}

Configuration options

The logger has currently only one configuration option which must be at the root level of the config to be evaluated.

logLevel (optional)

Type	String or LogLevel
Default	LogLevel.info

The log level for the logger

Related classes

• Logger
• LogLevel