RubyGem: Logger for systemd-journal (donated to theforeman, kept as a mirror)
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
Lukas Zapletal 7abb01d0e5 Version 3.1.0 1 year ago
lib/journald Version 3.1.0 1 year ago
spec Added rubocop and rufo deps 4 years ago
.gitignore ignore .idea 9 years ago
.rubocop.yml Minimum Ruby version is 2.5 1 year ago
.travis.yml Support Ruby 2.7 3 years ago Version 3.1.0 1 year ago
Gemfile Added rubocop and rufo deps 4 years ago
LICENSE.txt Update LICENSE.txt 5 years ago Do not override Ruby send method 4 years ago
Rakefile Do not override Ruby send method 4 years ago
journald-logger.gemspec Minimum Ruby version is 2.5 1 year ago


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