journald-logger

A Logger drop-in replacement that logs directly to systemd-journal with some additional features

Usage

require 'journald/logger'

logger = Journald::Logger.new('gandalf') # simple logger, sets SYSLOG_IDENTIFIER to 'gandalf'
logger = Journald::TraceLogger.new('gandalf') # tracing logger, logs caller's file, line number and function name

Logger replacement

This gem is designed to be accurate drop-in Logger replacement

logger.warn "you shall not pass!"           # works
logger.info("gollum") { "my preciousss" }   # also works!
logger.progname = "saruman"                 # sets value for SYSLOG_IDENTIFIER to 'saruman'
logger.formatter = SomeFormatter.new        # does nothing, journald-logger does not require a formatter
logger.close                                # does nothing, nothing to close

We map Ruby severity to Syslog priority by this map

LEVEL_MAP = {
  ::Logger::UNKNOWN => LOG_ALERT,
  ::Logger::FATAL   => LOG_CRIT,
  ::Logger::ERROR   => LOG_ERR,
  ::Logger::WARN    => LOG_WARNING,
  ::Logger::INFO    => LOG_INFO,
  ::Logger::DEBUG   => LOG_DEBUG,
}

You may notice it's somewhat different from the one from Syslog::Logger

Setting report level

logger = Journald::Logger.new('gandalf', Journald::LOG_NOTICE) # set minimal reporting level to notice
logger.min_priority   = Journald::LOG_NOTICE # runtime change of minimal priority
logger.level          = Logger::WARN # use Logger severity
logger.sev_threshold  = Logger::INFO # please pay attention that Logger severity lacks several levels e.g. 'notice'

Tags

Tags are used to add systemd-journal fields to all subsequent log calls until removed

logger = Journald::Logger.new('gandalf', world: 'arda') # set world tag in costructor
logger.tag location: 'shire', weapon: 'staff' # add/replace location and weapon
logger.tag(location: 'moria', object: 'balrog') do # change location and use object in the block
  # log as 'MESSAGE=you shall not pass!', 'PRIORITY=4', 'LOCATION=moria', 'OBJECT=balrog', 'WORLD=arda', 'WEAPON=staff'
  logger.warn 'you shall not pass!'
end # return location & object to the previous state
# log as 'MESSAGE=That was not in canon!', 'PRIORITY=6', 'LOCATION=shire', 'WORLD=arda', 'WEAPON=staff'
logger.info 'That was not in canon!'
logger.untag :location, :weapon # remove location and weapon

Tag names must follow systemd-journal fields naming convention: letters, numbers, underscores, cannot begin with underscore. Library upcases all letters automatically

systemd-journal style

Two methods which look similarly to native systemd-journal api

logger.send_message(
  message: 'hi!',
  priority: Journald::LOG_NOTICE,
  any_field: 'any_value',
) # tags will be added here
logger.print Journald::LOG_NOTICE, 'hi!' # and here

Syslog style

Just to add some more confusion you may use methods with syslog severity names prefixed with log_

logger.log_err 'Error'
logger.log_debug 'Debug'

Exception logging

begin
  raise "Aw, snap!"
rescue => e
  logger.exception e # log exception with LOG_ERR level by default
  logger.exception e, severity: Logger::WARN        # use Logger severity
  logger.exception e, priority: Journald::LOG_ALERT # use Syslog priority 
end

Exception logger automatically fills the following fields:

EXCEPTION_CLASS=ExceptionRealClassName
EXCEPTION_MESSAGE=Original exception message
BACKTRACE=full backtrace
CAUSE=exception cause (Ruby >= 2.1)
GEM_LOGGER_MESSAGE_TYPE=Exception

In Ruby 2.1+ it also tries to log CODE_LINE, CODE_FILE and CODE_FUNC and to recurse into Cause and log it into a separate message with GEM_LOGGER_MESSAGE_TYPE=ExceptionCause

Authors

This library was written by Anton Smirnov and currently maintained by https://www.theforeman.org developers.

License

MIT, see LICENSE.txt