模組 Syslog

syslog 套件提供 Ruby 介面，可使用 POSIX 系統記錄功能。

Syslog 訊息通常會傳遞至中央記錄守護程式。守護程式可能會篩選這些訊息；將它們路由到不同的檔案（通常會在 /var/log 下找到）；將它們置於 SQL 資料庫中；透過 TCP 或 UDP 將它們轉送至集中式記錄伺服器；甚至可以透過電子郵件、呼叫器或簡訊通知系統管理員。

與透過 Logger 或 Log4r 進行的應用程式層級記錄不同，syslog 的設計目的是允許進行安全的防竄改記錄。

syslog 協定已在 RFC 5424 中標準化。

常數

VERSION: Syslog 巨集

公開類別方法

close() 按一下以切換來源

關閉 syslog 功能。如果未開啟，則會引發執行時期例外狀況。

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() 按一下以切換來源

傳回 open() 最後一次呼叫中使用的功能編號

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

ident() 按一下以切換來源

傳回 open() 最後一次呼叫中使用的身分識別字串

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

inspect() 按一下以切換來源

傳回摘要物件狀態的 inspect() 字串。

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() 按一下以切換來源

傳回 self，以維持向後相容性。

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

log(priority, format_string, *format_args) 按一下以切換來源

記錄優先順序指定的訊息。範例

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

優先順序層級（由高至低）為

LOG_EMERG: 系統無法使用
LOG_ALERT: 需要立即採取行動
LOG_CRIT: 發生嚴重狀況
LOG_ERR: 發生錯誤
LOG_WARNING: 警告可能發生問題
LOG_NOTICE: 發生正常但重要的狀況
LOG_INFO: 資訊訊息
LOG_DEBUG: 偵錯資訊

每個優先順序等級也有一個捷徑方法，會以其命名的優先順序進行記錄。例如，下列兩個陳述式會產生相同的結果

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() 按一下以切換來源

傳回目前有效的記錄優先順序遮罩。開啟或關閉 syslog 時不會重設遮罩。

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

mask=(priority_mask) 按一下以切換來源

設定記錄優先順序遮罩。定義一個 LOG_UPTO 方法，讓設定遮罩值更容易。範例

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

或者，可以使用二進位 OR 選擇特定優先順序並將其加總。範例

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

優先順序遮罩會持續存在於 open() 和 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 按一下以切換來源

開啟 syslog 設施。如果已開啟，則會引發執行時期例外狀況。

可以呼叫，也可以不呼叫程式區塊。如果呼叫時帶有區塊，則會將建立的 Syslog 物件傳遞給區塊。

如果 syslog 已開啟，則會引發 RuntimeError。

ident 是識別呼叫程式的 字串。

options 是下列任一項的邏輯 OR

LOG_CONS: 如果傳送至系統記錄器時發生錯誤，則直接寫入主控台。
LOG_NDELAY: 立即開啟連線，而不是等到寫入第一則訊息時才開啟。
LOG_NOWAIT: 不要等到記錄訊息時建立的任何子程序。 (對 Linux 沒有影響。)
LOG_ODELAY: LOG_NDELAY 的相反；在開啟連線前等候訊息傳送。（這是預設值。）
LOG_PERROR: 將訊息列印到 stderr，並將其傳送至 syslog。（不在 POSIX.1-2001 中。）
LOG_PID: 在每個訊息中包含目前的處理程序 ID。

facility 描述開啟 syslog 的程式類型，並為下列任何一個的邏輯 OR，這些都是為主機作業系統定義的

LOG_AUTH: 安全性或授權。已棄用，請改用 LOG_AUTHPRIV。
LOG_AUTHPRIV: 應保持私密的安全性或授權訊息。
LOG_CONSOLE: 系統主控台訊息。
LOG_CRON: 系統工作排程器 (cron 或 at)。
LOG_DAEMON: 沒有自己的 facility 值的系統守護程式。
LOG_FTP: FTP 伺服器。
LOG_KERN: 核心訊息（無法由使用者處理程序傳送，因此對 Ruby 沒有多大用處，但在此列出以求完整）。
LOG_LPR: 列印機子系統。
LOG_MAIL: 郵件傳遞或傳輸子系統。
LOG_NEWS: Usenet 新聞系統。
LOG_NTP: 網路時間通訊協定伺服器。
LOG_SECURITY: 一般安全性訊息。
LOG_SYSLOG: 由 syslog 內部產生的訊息。
LOG_USER: 一般使用者層級訊息。
LOG_UUCP: UUCP 子系統。
LOG_LOCAL0 至 LOG_LOCAL7: 區域定義的 facility。

範例

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 按一下以切換原始碼

關閉並重新開啟 syslog。

參數與 open() 相同。

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

    return mSyslog_open(argc, argv, self);
}

opened? 按一下以切換原始碼

如果 syslog 已開啟，則傳回 true。

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

options() 按一下以切換原始碼

傳回 open() 最後一次呼叫中使用的選項位元遮罩

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

reopen(ident, options, facility) → syslog 按一下以切換原始碼

關閉並重新開啟 syslog。

參數與 open() 相同。

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

    return mSyslog_open(argc, argv, self);
}