Module: Syslog (Ruby 2.2.3)
Description: Module : Syslog - Ruby 2.2.3

- Home
- Core 2.2.3
- Std-lib 2.2.3
- Downloads

Support for the Ruby 2.2 series has ended. See here for reference.

### Home Classes Methods

### In Files

- syslog/lib/syslog/logger.rb
- syslog/syslog.c

### Namespace

- MODULE Syslog::Constants
- MODULE Syslog::Facility
- MODULE Syslog::Level
- MODULE Syslog::Macros
- MODULE Syslog::Option
- CLASS Syslog::Logger

### Methods

- ::close
- ::facility
- ::ident
- ::inspect
- ::instance
- ::log
- ::mask
- ::mask=
- ::open
- ::open!
- ::opened?
- ::options
- ::reopen

### Class/Module Index

Quicksearch

- Syslog
- Syslog::Constants
- Syslog::Facility
- Syslog::Level
- Syslog::Logger
- Syslog::Logger::Formatter
- Syslog::Logger::Severity
- Syslog::Macros
- Syslog::Option

No matching classes.

# 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.

### 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")

Format strings are as for printf/sprintf, except that in addition %m is replaced with the error message string that would be returned by strerror(errno).

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

        if (argc < 2) {
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 2+)", argc);
        }

        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;

        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");
        }
        SafeStringValue(ident);
        syslog_ident = strdup(RSTRING_PTR(ident));

        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);
    }