RubyGem: Logger for systemd-journal (donated to theforeman, kept as a mirror)
Go to file
Lukas Zapletal 7abb01d0e5 Version 3.1.0 2022-03-30 08:42:06 +02:00
lib/journald Version 3.1.0 2022-03-30 08:42:06 +02:00
spec Added rubocop and rufo deps 2019-12-02 14:31:30 +01:00
.gitignore ignore .idea 2014-12-03 20:28:03 +03:00
.rubocop.yml Minimum Ruby version is 2.5 2022-03-30 08:39:37 +02:00
.travis.yml Support Ruby 2.7 2020-05-06 10:19:53 +02:00 Version 3.1.0 2022-03-30 08:42:06 +02:00
Gemfile Added rubocop and rufo deps 2019-12-02 14:31:30 +01:00
LICENSE.txt Update LICENSE.txt 2018-10-09 14:40:47 +03:00 Do not override Ruby send method 2019-12-03 12:05:54 +01:00
Rakefile Do not override Ruby send method 2019-12-03 12:05:54 +01:00
journald-logger.gemspec Minimum Ruby version is 2.5 2022-03-30 08:39:37 +02:00


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


require 'journald/logger'

logger ='gandalf') # simple logger, sets SYSLOG_IDENTIFIER to 'gandalf'
logger ='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"gollum") { "my preciousss" }   # also works!
logger.progname = "saruman"                 # sets value for SYSLOG_IDENTIFIER to 'saruman'
logger.formatter =        # 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

  ::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 ='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 are used to add systemd-journal fields to all subsequent log calls until removed

logger ='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' '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

  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

  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 

Exception logger automatically fills the following fields:

EXCEPTION_MESSAGE=Original exception message
BACKTRACE=full backtrace
CAUSE=exception cause (Ruby >= 2.1)

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


This library was written by Anton Smirnov and currently maintained by developers.


MIT, see LICENSE.txt