Serilog.Sinks.SyslogMessages 1.0.5

Serilog.Sinks.SyslogMessages

A Serilog sink that logs events to remote syslog servers using both UDP and TCP (including over TLS), and can also use POSIX libc syslog functions to write to the local syslog service on Linux systems. Both RFC3164 and RFC5424 format messages are supported.

Getting started

Install the Serilog.Sinks.SyslogMessages package from NuGet:

Install-Package Serilog.Sinks.SyslogMessages

To configure the sink to write messages to a remote syslog service over UDP, call WriteTo.UdpSyslog() during logger configuration:

var log = new LoggerConfiguration()
    .WriteTo.UdpSyslog("10.10.10.14")
    .CreateLogger();

To configure the sink to write messages to a remote syslog service over TCP, call WriteTo.TcpSyslog() during logger configuration:

var log = new LoggerConfiguration()
    .WriteTo.TcpSyslog("10.10.10.14")
    .CreateLogger();

To configure the sink to write messages to the local syslog service on Linux systems, call WriteTo.LocalSyslog() during logger configuration:

var log = new LoggerConfiguration()
    .WriteTo.LocalSyslog()
    .CreateLogger();

A number of optional parameters are available for more advanced configurations, with more details in the following sections.

Message Format

This sink supports RFC3164 and RFC5424 format messages, as well as a basic 'local' format which is suitable for use with the LocalSyslog sink. The default is RFC3164 for the UDP sink, and RFC5424 for the TCP sink. RFC5424 is more capable format, and should be used when possible - for example, it supports full timestamps that include the local time offset. It also supports structured data, and these sinks will write Serilog properties to the STRUCTURED-DATA field.

To configure the format, use the format parameter:

var log = new LoggerConfiguration()
    .WriteTo.UdpSyslog("10.10.10.14", format: SyslogFormat.RFC5424)
    .CreateLogger();

Examples

An example of an RFC3164 message:

<12>Dec 19 04:01:02 MYHOST MyApp[1912]: [Source.Context] This is a test message

An example of an RFC5424 message:

<12>1 2013-12-19T04:01:02.357852+00:00 MYHOST MyApp 1912 Source.Context [meta Property1="A Value" AnotherProperty="Another Value" SourceContext="Source.Context"] This is a test message

Message Framing

When using TCP, messages can be framed in a variety of ways. Historically, servers have accepted messages terminated with a newline, carriage return, newline and carriage return, or nul. More fully-featured syslog servers also support a more transparent framing method, where each message is prefixed with its length. This 'octet-counting' method is described in RFC5425 and RFC6587.

To configure the framing method, use the framingType parameter:

var log = new LoggerConfiguration()
    .WriteTo.TcpSyslog("10.10.10.14", framingType: FramingType.OCTET_COUNTING)
    .CreateLogger();

Secure Communication

The TcpSink supports TLS-enabled syslog servers that implement RFC5425 (such as Rsyslog). Mutual authentication is also supported. A full example:

var tcpConfig = new SyslogTcpConfig
{
    Host = "10.10.10.14",
    Port = 6514,
    Formatter = new Rfc5424Formatter(),
    Framer = new MessageFramer(FramingType.OCTET_COUNTING),
    SecureProtocols = SslProtocols.Tls11 | SslProtocols.Tls12,
    CertProvider = new CertificateFileProvider("MyClientCert.pfx"),
    CertValidationCallback = (sender, certificate, chain, sslPolicyErrors) =>
    {
        // Check the server certificate here
        return true;
    }
};

var log = new LoggerConfiguration()
    .WriteTo.TcpSyslog(tcpConfig)
    .CreateLogger();

SyslogTcpConfig properties:

SecureProtocols: defines which protocols can be negotiated with the syslog server.

CertProvider: can optionally be set if the syslog server requires client authentication. Various ICertificateProviders are provided, to load a certificate from disk, the Certificate Store, or for you to pass in a certificate from any other source.

CertValidationCallback: can optionally be set if you want to perform your own authentication of the syslog server's certificate. If not set, the system default will be used (the certificate must chain to a trusted root in the Certificate Store).

If SecureProtocols is SecureProtocols.None,

Additional optional parameters

var log = new LoggerConfiguration()
    .WriteTo.UdpSyslog(host: "10.10.10.14", port: 514, appName: "my-app", format: SyslogFormat.RFC5424, facility: SyslogFacility.Local1, outputTemplate: "{Message}")
    .CreateLogger();

host and port define the address the remote syslog server is listening at.

app-name is the name of your application, which will be included in the TAG field when using RFC3164 format, or the APP-NAME field when using RFC5424 format. If not set, this will be defaulted to the name of the current process.

format defines whether messages are sent in RFC3164, RFC5424 or 'local' format - see the Message Format section above for more information.

facility The syslog 'facility' defines the category of the system or application that is generating the log message. The default is Local0, but it can be set to any of the values as defined in the syslog RFCs.

outputTemplate Controls the format of the 'body' part of messages. See https://github.com/serilog/serilog/wiki/Formatting-Output.

restrictedToMinimumLevel The minimum level for log events to pass through the sink. See https://github.com/serilog/serilog/wiki/Configuration-Basics#minimum-level.

Enabling support for RFC5424 messages

Rsyslog normally defaults to RFC3164 format messages, but can write RFC5424 format messages by changing the $ActionFileDefaultTemplate property in /etc/rsyslog.conf:

$ActionFileDefaultTemplate RSYSLOG_SyslogProtocol23Format

Copyright © 2018 Ionx Solutions - Provided under the Apache License, Version 2.0.