模块 Syslog

syslog 包为 POSIX 系统日志记录设施提供了一个 Ruby 接口。

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: 没有自身设施值的系统守护进程。
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: 本地定义的设施。

示例

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