Syslog NIF

An Erlang logger backend for Unix syslog.

This is a small, fast, stable handler for OTP 21+ applications that need to record log events to the Unix syslog subsystem.

Usage

syslog appears to OTP as an application, so it can (and in most cases should) be started automatically by adding syslog to the applications list in your <project>.app file, normally compiled from the <dir>/src/<project>.app.src file.

{application, sample, [
    {description,   "A sample Erlang application"},
    . . .
    {applications, [
        kernel,
        stdlib,
        syslog,     %% <== include early in the list
        . . .
    ]},
    . . .

Here, starting the sample application will in turn cause the syslog application to be started with the configuration described below.

The application is configured like any other in your sys.config file. An example might look like the following:

[
    {kernel, [
        %% consider disabling the default log handler if you ONLY want
        %% syslog output, in which case you should make sure the syslog
        %% application is loaded early in your application's dependencies.
        {logger, [{handler, default, undefined}]}
    ]},
    {syslog, [

        %% openlog initialization values
        {identity,  "SampleApp"},
        {facility,  local0},    %% may be overridden by handlers
        {options,   [pid, cons, perror]},

        %% logger handlers, see below
        {logger, [
            {handler, fast_handler, syslog, #{
                config => user, formatter => {syslog, #{
                    depth => 5, max_size => 512
            }}}},
            {handler, alt_handler, syslog, #{config => local3,
                formatter => {logger_formatter, #{single_line => true,
                template => [level," ",pid,":",mfa,":",line,": ",msg]
            }}}}
        ]}
    ]},
    . . .
].

With this configuration, syslog will cause the configured handlers to be loaded once its own initialization is complete.

Why are the logger handlers specified in the syslog section instead of under kernel where the OTP docs tell me to put them?

Configuring the syslog logger handlers inside the syslog section ensures that the syslog application is up and running before the handlers are added. Adding the handlers in the kernel -> logger section may result in the handlers being added before the syslog application is started, resulting in obscure noproc exceptions.

Configuration

identity is a string or atom representing your program's name to be included in syslog records. If not specified, it defaults to the name your program was started with.

facility is one of

    kernel          %% you probably shouldn't be using this
    user            %% the default if not specified
    mail            %% mail subsystem
    daemon          %% long-running background servers
    auth            %% security/authorization messages
    lpr             %% line printer subsystem
    news            %% network news subsystem
    uucp            %% UUCP subsystem
    cron            %% cron subsystem
    authpriv        %% private security/authorization messages
    ftp             %% FTP daemon
    local0 - local7 %% locally defined classifications

options is a list containing any combination of the following:

    pid             %% log the process ID with each message
    cons            %% log to the system console if logging facility unavailable
    ndelay          %% open the connection to the logging facility immediately
    odelay          %% delay logging facility connection until a log is written
    nowait          %% low-level option, generally deprecated, look it up
    perror          %% log to standard error stream as well

If not specified, options defaults to [pid, cons].

Handlers are configured as documented for the logger application. syslog handlers' configuration is a single facility atom, or the atom default to use the global syslog setting:

{logger, [
    {handler, <handler-name>, syslog,
        #{config => <facility> | 'default', ...} }
    . . .
]}

Handlers may also be added and configured through logger:add_handler/3 and related functions.

Building

syslog_nif is a small Rebar3 project that should build and function properly on any current Erlang/OTP Unix platform with a standard C compiler.

Add the following dependency to your rebar.config file's deps section and build your project:

{deps, [
    . . .
    {syslog, {git, "<this-repo-url>.git", {branch, "master"}}}
]}.

If you're packaging your application with relx be sure to include syslog in the list of packaged libraries. Again, adding it near the head of the list is recommended.

Platform Support

The syslog handler supports Linux, BSD, and macOS operating systems.

Other Unix systems may work but are untested.

Implementation

The implementation relies on OS conformance to the IEEE syslog API and IETF syslog protocol standards, supported by all common Unix variants.

Based on this widespread support, we're able to translate directly between atoms representing facilities, levels, and severities and their integral mappings in simple optimized Erlang code to keep the NIF itself small, uncluttered, and fast.

The logging path is optimized for througput, so don't expect to learn much by inspecing the runtime handler configuration without the code in front of you.

Facility 5 (syslog) is reserved for internal syslog use.
Facilities 12-15 vary across platforms and are reserved for system use.
Facility may be specified as an integer in the range 0..23 to circumvent the above limitations, but this usage is strongly discouraged!

Bugs

What??? No way ...

Yeah, you should probably file an issue.