////
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

         http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
////

[#remotesyslogappender]
= RemoteSyslogAppender

The `RemoteSyslogAppender` sends log messages to a remote syslog daemon using the BSD syslog protocol over UDP (default port 514).
It supports configurable syslog facilities and severity levels, but due to the nature of UDP, messages may be lost or truncated.

This appender does not include timestamp or hostname fields, as the receiving syslog daemon adds them automatically.
It also splits log messages at line breaks, sending each line as a separate syslog message.

The following example sends all events with Level WARN or higher to the remote server 192.168.1.100 on the default port with UTF8-Encoding.

[source,xml]
----
<appender name="RemoteSyslogAppender" type="log4net.Appender.RemoteSyslogAppender">
  <encoding>UTF-8</encoding>
  <layout type="log4net.Layout.PatternLayout">
    <conversionPattern value="%date{MM/dd/yyyy HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline" />
  </layout>
  <remoteAddress value="192.168.1.100" />
  <threshold value="WARN" />
</appender>
----

You can also specify:

* Facility (default: user)
* Identity (default: application name)

[source,xml]
----
<appender name="RemoteSyslogAppender" type="log4net.Appender.RemoteSyslogAppender">
  <encoding>UTF-8</encoding>
  <facility>Alert</facility>
  <layout type="log4net.Layout.PatternLayout">
    <conversionPattern value="%date{MM/dd/yyyy HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline" />
  </layout>
  <identity>MyApp-Canary</identity>
  <remoteAddress value="192.168.1.100" />
  <threshold value="WARN" />
</appender>
----

[#newlinehandling]
== Newline handling

Newline handling changed in version 3.3.0.

Before version 3.3.0, newline characters (`\r` or `\n`) were always treated as line breaks.
Messages containing newlines were therefore split into multiple syslog entries.

Starting with 3.3.0, newline handling is configurable through the `NewLineHandling` option.
The new default is `Escape`.

The available modes are:

`Escape` (default since 3.3.0)::
  Newlines are replaced with the escaped representations `\r` → "\\r" and `\n` → "\\n".
  The message is sent as a single syslog entry.

`Split` (default before 3.3.0)::
  The message is split at each newline into multiple syslog entries.
  Combined sequences (\r\n) count as a single break.
  This matches the behaviour in versions before 3.3.0.

`Keep`::
  Newlines are preserved as-is in the message content.
  Many syslog servers can process entries containing embedded newlines, but server support varies.

=== Example: Escape

Input:

[source,csharp]
logger.Error("A\nB\r\nC");

Output (one syslog entry):

[source,log]
... ERROR ... - A\nB\rC

=== Example: Split

Input:

[source,csharp]
logger.Error("A\nB\r\nC");

Output (three syslog entries, unrelated messages may interleave):

[source,log]
... ERROR ... - A
... ERROR ... - B
... INFO  ... - something unrelated
... ERROR ... - C

=== Example: Keep

Input:

[source,csharp]
logger.Error("A\nB\r\nC");

Output (one syslog entry, with embedded newlines):

[source,log]
... ERROR ... - A
B
C

[#sizelimits]
== Size limits

The `RemoteSyslogAppender` uses the UDP protocol to send log messages to the syslog server.
However, there are size limitations associated with UDP:

* **Message size:** Each log message is limited to **64 KB**, including both the message content and the headers.
* **Practical size limit:** On many networks, such as Ethernet, the practical limit for message size is typically much lower — around **1500 bytes**.
* **Message truncation:** If a log message exceeds these size limits, it will be **truncated**, which means some of the message content will be lost.

To avoid truncation, ensure that log messages are kept within the size limits of your network setup.