module Syslog - Documentation for Ruby 3.3

# module Syslog

The syslog package provides a Ruby interface to the POSIX system logging facility.

`Syslog` messages are typically passed to a central logging daemon. The daemon may filter them; route them into different files (usually found under /var/log); place them in SQL databases; forward them to centralized logging servers via TCP or UDP; or even alert the system administrator via email, pager or text message.

Unlike application-level logging via `Logger` or Log4r, syslog is designed to allow secure tamper-proof logging.

The syslog protocol is standardized in RFC 5424.

### Constants

VERSION

  `Syslog` macros

### Public Class Methods

close() click to toggle source

Closes the syslog facility. Raises a runtime exception if it is not open.

    static VALUE mSyslog_close(VALUE self)
    {
        if (!syslog_opened) {
            rb_raise(rb_eRuntimeError, "syslog not opened");
        }

        closelog();

        xfree((void *)syslog_ident);
        syslog_ident = NULL;
        syslog_options = syslog_facility = syslog_mask = -1;
        syslog_opened = 0;

        return Qnil;
    }

facility() click to toggle source

Returns the facility number used in the last call to open()

    static VALUE mSyslog_facility(VALUE self)
    {
        return syslog_opened ? INT2NUM(syslog_facility) : Qnil;
    }

ident() click to toggle source

Returns the identity string used in the last call to open()

    static VALUE mSyslog_ident(VALUE self)
    {
        return syslog_opened ? rb_str_new2(syslog_ident) : Qnil;
    }

inspect() click to toggle source

Returns an inspect() string summarizing the object state.

    static VALUE mSyslog_inspect(VALUE self)
    {
        Check_Type(self, T_MODULE);

        if (!syslog_opened)
            return rb_sprintf("<#%"PRIsVALUE": opened=false>", self);

        return rb_sprintf("<#%"PRIsVALUE": opened=true, ident=\"%s\", options=%d, facility=%d, mask=%d>",
                          self,
                          syslog_ident,
                          syslog_options,
                          syslog_facility,
                          syslog_mask);
    }

instance() click to toggle source

Returns self, for backward compatibility.

    static VALUE mSyslog_instance(VALUE self)
    {
        return self;
    }

log(priority, format_string, *format_args) click to toggle source

Log a message with the specified priority. Example:

    Syslog.log(Syslog::LOG_CRIT, "Out of disk space")
    Syslog.log(Syslog::LOG_CRIT, "User %s logged in", ENV['USER'])

The priority levels, in descending order, are:

LOG_EMERG

  System is unusable

LOG_ALERT

  Action needs to be taken immediately

LOG_CRIT

  A critical condition has occurred

LOG_ERR

  An error occurred

LOG_WARNING

  `Warning` of a possible problem

LOG_NOTICE

  A normal but significant condition occurred

LOG_INFO

  Informational message

LOG_DEBUG

  Debugging information

Each priority level also has a shortcut method that logs with it’s named priority. As an example, the two following statements would produce the same result:

    Syslog.log(Syslog::LOG_ALERT, "Out of memory")
    Syslog.alert("Out of memory")

    static VALUE mSyslog_log(int argc, VALUE *argv, VALUE self)
    {
        VALUE pri;

        rb_check_arity(argc, 2, UNLIMITED_ARGUMENTS);

        argc--;
        pri = *argv++;

        if (!FIXNUM_P(pri)) {
            rb_raise(rb_eTypeError, "type mismatch: %"PRIsVALUE" given", rb_obj_class(pri));
        }

        syslog_write(FIX2INT(pri), argc, argv);

        return self;
    }

mask() click to toggle source

Returns the log priority mask in effect. The mask is not reset by opening or closing syslog.

    static VALUE mSyslog_get_mask(VALUE self)
    {
        return syslog_opened ? INT2NUM(syslog_mask) : Qnil;
    }

mask=(priority_mask) click to toggle source

Sets the log priority mask. A method LOG_UPTO is defined to make it easier to set mask values. Example:

    Syslog.mask = Syslog::LOG_UPTO(Syslog::LOG_ERR)

Alternatively, specific priorities can be selected and added together using binary OR. Example:

    Syslog.mask = Syslog::LOG_MASK(Syslog::LOG_ERR) | Syslog::LOG_MASK(Syslog::LOG_CRIT)

The priority mask persists through calls to open() and close().

    static VALUE mSyslog_set_mask(VALUE self, VALUE mask)
    {
        if (!syslog_opened) {
            rb_raise(rb_eRuntimeError, "must open syslog before setting log mask");
        }

        setlogmask(syslog_mask = NUM2INT(mask));

        return mask;
    }

open(ident, options, facility) → syslog click to toggle source

Open the syslog facility. Raises a runtime exception if it is already open.

Can be called with or without a code block. If called with a block, the `Syslog` object created is passed to the block.

If the syslog is already open, raises a `RuntimeError`.

`ident` is a `String` which identifies the calling program.

`options` is the logical OR of any of the following:

LOG_CONS

  If there is an error while sending to the system logger, write directly to the console instead.

LOG_NDELAY

  Open the connection now, rather than waiting for the first message to be written.

LOG_NOWAIT

  Don’t wait for any child processes created while logging messages. (Has no effect on Linux.)

LOG_ODELAY

  Opposite of LOG_NDELAY; wait until a message is sent before opening the connection. (This is the default.)

LOG_PERROR

  Print the message to stderr as well as sending it to syslog. (Not in POSIX.1-2001.)

LOG_PID

  Include the current process ID with each message.

`facility` describes the type of program opening the syslog, and is the logical OR of any of the following which are defined for the host OS:

LOG_AUTH

  Security or authorization. Deprecated, use LOG_AUTHPRIV instead.

LOG_AUTHPRIV

  Security or authorization messages which should be kept private.

LOG_CONSOLE

  System console message.

LOG_CRON

  System task scheduler (cron or at).

LOG_DAEMON

  A system daemon which has no facility value of its own.

LOG_FTP

  An FTP server.

LOG_KERN

  A kernel message (not sendable by user processes, so not of much use to Ruby, but listed here for completeness).

LOG_LPR

  Line printer subsystem.

LOG_MAIL

  Mail delivery or transport subsystem.

LOG_NEWS

  Usenet news system.

LOG_NTP

  Network `Time` Protocol server.

LOG_SECURITY

  General security message.

LOG_SYSLOG

  Messages generated internally by syslog.

LOG_USER

  Generic user-level message.

LOG_UUCP

  UUCP subsystem.

LOG_LOCAL0 to LOG_LOCAL7

  Locally-defined facilities.

Example:

    Syslog.open("webrick", Syslog::LOG_PID,
                Syslog::LOG_DAEMON | Syslog::LOG_LOCAL3)

    static VALUE mSyslog_open(int argc, VALUE *argv, VALUE self)
    {
        VALUE ident, opt, fac;
        const char *ident_ptr;

        if (syslog_opened) {
            rb_raise(rb_eRuntimeError, "syslog already open");
        }

        rb_scan_args(argc, argv, "03", &ident, &opt, &fac);

        if (NIL_P(ident)) {
            ident = rb_gv_get("$0");
        }
        ident_ptr = StringValueCStr(ident);
        syslog_ident = strdup(ident_ptr);

        if (NIL_P(opt)) {
            syslog_options = LOG_PID | LOG_CONS;
        } else {
            syslog_options = NUM2INT(opt);
        }

        if (NIL_P(fac)) {
            syslog_facility = LOG_USER;
        } else {
            syslog_facility = NUM2INT(fac);
        }

        openlog(syslog_ident, syslog_options, syslog_facility);

        syslog_opened = 1;

        setlogmask(syslog_mask = setlogmask(0));

        /* be like File.new.open {...} */
        if (rb_block_given_p()) {
            rb_ensure(rb_yield, self, mSyslog_close, self);
        }

        return self;
    }

reopen(ident, options, facility) → syslog click to toggle source

Closes and then reopens the syslog.

Arguments are the same as for open().

    static VALUE mSyslog_reopen(int argc, VALUE *argv, VALUE self)
    {
        mSyslog_close(self);

        return mSyslog_open(argc, argv, self);
    }

opened? click to toggle source

Returns true if the syslog is open.

    static VALUE mSyslog_isopen(VALUE self)
    {
        return syslog_opened ? Qtrue : Qfalse;
    }

options() click to toggle source

Returns the options bitmask used in the last call to open()

    static VALUE mSyslog_options(VALUE self)
    {
        return syslog_opened ? INT2NUM(syslog_options) : Qnil;
    }

reopen(ident, options, facility) → syslog click to toggle source

Closes and then reopens the syslog.

Arguments are the same as for open().

    static VALUE mSyslog_reopen(int argc, VALUE *argv, VALUE self)
    {
        mSyslog_close(self);

        return mSyslog_open(argc, argv, self);
    }