123456789_123456789_123456789_123456789_123456789_

Module: Syslog

Relationships & Source Files
Namespace Children
Modules:
Constants, Facility, Level, Macros, Option
Classes:
Logger
Defined in: ext/syslog/syslog.c

Overview

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.

Class Attribute Summary

Class Method Summary

Class Attribute Details

.mask (rw, mod_func)

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

[ GitHub ] 

  


# File 'ext/syslog/syslog.c', line 243



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


  








  

    .mask=(priority_mask)   (rw, mod_func)  



  

    

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().


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 263



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


  








  

    .opened?  ⇒ Boolean  (readonly, mod_func)  



  

    

Returns true if the syslog is open.


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 214



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


  







Class Method Details



  

    .close   (mod_func)
  



  

    

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


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 56



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   (mod_func)
  



  

    

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


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 235



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


  








  

    .ident   (mod_func)
  



  

    

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


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 221



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


  








  

    .inspect  
  



  

    

Returns an inspect() string summarizing the object state.


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 320



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   (mod_func)
  



  

    

Returns self, for backward compatibility.


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 337



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


  








  

    .log(priority, format_string, *format_args)   (mod_func)  



  

    

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


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 300



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


  








  

    .open(ident, options, facility)  ⇒ Syslog  (mod_func)  



  

    

:yields: syslog



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)


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 150



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


  








  

    .open!(ident, options, facility)  ⇒ Syslog  (mod_func)    Also known as: .reopen
  



  

    

:yields: syslog



Closes and then reopens the syslog.



Arguments are the same as for open().


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 202



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

    return mSyslog_open(argc, argv, self);
}


  








  

    .options   (mod_func)
  



  

    

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


  



  [ GitHub ]


  

  


# File 'ext/syslog/syslog.c', line 228



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


  








  

    

      .open!(ident, options, facility)  ⇒ Syslog  (mod_func)
      .reopen(ident, options, facility)  ⇒ Syslog 
    

  



  

    

Alias for .open!.