added localsyslogappender doc

FreeAndNil · FreeAndNil · commit 085d26862a7e · 2025-04-02T19:49:55.000+02:00
revised appender descriptions
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
@@ -29,6 +29,7 @@
 **** xref:manual/configuration/fileappender.adoc[]
 **** xref:manual/configuration/rollingfileappender.adoc[]
 **** xref:manual/configuration/forwardingappender.adoc[]
+**** xref:manual/configuration/localsyslogappender.adoc[]
 **** xref:manual/configuration/managedcoloredconsoleappender.adoc[]
 **** xref:manual/configuration/memoryappender.adoc[]
 **** xref:manual/configuration/outputdebugstringappender.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
@@ -48,6 +48,9 @@ log4net ships with the following appenders
 |AspNetTraceAppender
 |Writes logging events to the ASP trace context. These can then be rendered at the end of the ASP page or on the ASP trace page.
 
+|BufferingForwardingAppender
+|Buffers events and then forwards them to attached appenders.
+
 |ColoredConsoleAppender
 |Writes color highlighted logging events to the application's Windows Console.
 
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/adonetappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/adonetappender.adoc
@@ -18,14 +18,23 @@
 [#adonetappender]
 = AdoNetAppender
 
-The configuration of the AdoNetAppender depends on the provider selected for the target database.
+The `AdoNetAppender` is used to log events directly to a database table.
+It writes log events in batches (with a default size of 100, controlled by the `BufferSize` setting).
 
-The following examples show how to configure the AdoNetAppender to log messages to different databases.
-The events are written in batches of 100 (BufferSize).
-The ConnectionType specifies the fully qualified type name for the System.Data.IDbConnection to use to connect to the database.
-The ConnectionString is database provider specific.
-The CommandText is either a prepared statement or a stored procedure, in this case it is a prepared statement.
-Each parameter to the prepared statement or stored procedure is specified with its name, database type and a layout that renders the value for the parameter.
+The configuration of `AdoNetAppender` depends on the database provider you're using.
+Here are the key configuration elements:
+
+* `ConnectionType`: Specifies the fully qualified type name for the `System.Data.IDbConnection` used to connect to the database.
+* `ConnectionString`: The connection string that is specific to the database provider (e.g., SQL Server, MySQL).
+* `CommandText`: Defines the SQL command to execute. This can either be a prepared statement or a stored procedure. In the examples below, a prepared statement is used.
+
+Each parameter in the prepared statement or stored procedure is defined with:
+
+* `Name`: The name of the parameter.
+* `DbType`: The database type for the parameter.
+* `Layout`: The layout used to render the value for the parameter.
+
+The following examples illustrate how to configure the `AdoNetAppender` for different databases.
 
 [#mssqlserver]
 == MS SQL Server
@@ -273,8 +282,8 @@ The appender configuration is:
 [#other-databases]
 == Other databases
 
-You can adjust the provided examples to other databases by
+To adapt the provided examples for use with other databases, follow these steps:
 
-* find a nuget package for connecting via ado.net
-* adjust the create table script (tweaking the used data types)
-* adjust the connectionType-Property in AdoNetAppender config to the connection type from the nuget package
+* Find a NuGet package that provides the necessary ADO.NET provider for your database.
+* Modify the `CREATE TABLE` script to match the data types used by your database.
+* Update the `ConnectionType` property in the `AdoNetAppender` configuration to reference the connection type from the selected NuGet package.
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/bufferingforwardingappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/bufferingforwardingappender.adoc
@@ -18,6 +18,10 @@
 [#bufferingforwardingappender]
 = BufferingForwardingAppender
 
+The `BufferingForwardingAppender` buffers log events in memory before forwarding them to another appender.
+This helps improve performance by reducing the number of writes to the destination appender, especially in high-volume logging scenarios.
+Once the buffer reaches a specified size or time threshold, the events are forwarded to the target appender in a batch.
+
 The following example shows how to configure the `BufferingForwardingAppender` to buffer 100 messages before delivering them to the `ConsoleAppender`.
 
 [source,xml]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/coloredconsoleappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/coloredconsoleappender.adoc
@@ -18,8 +18,10 @@
 [#coloredconsoleappender]
 = ColoredConsoleAppender
 
+The `ColoredConsoleAppender` writes log messages to the console with color coding based on log levels.
+It allows configurable colors for each log level, making it easier to identify log severity.
+
 The following example shows how to configure the ColoredConsoleAppender to log messages to the console.
-By default the messages are sent to the console standard output stream.
 This example shows how to highlight error messages.
 
 [source,xml]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/consoleappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/consoleappender.adoc
@@ -18,6 +18,9 @@
 [#consoleappender]
 = ConsoleAppender
 
+The `ConsoleAppender` writes log messages to the console.
+It outputs messages without color coding, making it simple and suitable for basic logging needs.
+
 The following example shows how to configure the `ConsoleAppender` to log messages to the console.
 By default the messages are sent to the console standard output stream.
 
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/eventlogappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/eventlogappender.adoc
@@ -18,6 +18,9 @@
 [#eventlogappender]
 = EventLogAppender
 
+The EventLogAppender in log4net logs messages to the Windows Event Log.
+It is limited to .Net 4.x because it is Windows specific and .netstandard lacks support for writing to the Event Log.
+
 The following example shows how to configure the `EventLogAppender` to log to the Application event log on the local machine using the event Source of the AppDomain.FriendlyName.
 
 [source,xml]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/examples.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/examples.adoc
@@ -30,6 +30,7 @@ These examples are by no means exhaustive configurations for the appenders.
 * xref:manual/configuration/fileappender.adoc[]
 * xref:manual/configuration/rollingfileappender.adoc[]
 * xref:manual/configuration/forwardingappender.adoc[]
+* xref:manual/configuration/localsyslogappender.adoc[]
 * xref:manual/configuration/managedcoloredconsoleappender.adoc[]
 * xref:manual/configuration/memoryappender.adoc[]
 * xref:manual/configuration/outputdebugstringappender.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/fileappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/fileappender.adoc
@@ -18,14 +18,17 @@
 [#fileappender]
 = FileAppender
 
+The `FileAppender` writes log messages to a specified file.
+It can append to existing files or overwrite them, depending on the configuration.
+
 The following example shows how to configure the `FileAppender` to write messages to a file.
-The file specified is log-file.txt.
+The file specified is MyApp.log.
 The file will be appended to rather than overwritten each time the logging process starts.
 
 [source,xml]
 ----
 <appender name="FileAppender" type="log4net.Appender.FileAppender">
-  <file value="log-file.txt" />
+  <file value="MyApp.log" />
   <appendToFile value="true" />
   <layout type="log4net.Layout.PatternLayout">
     <conversionPattern value="%date [%thread] %-5level %logger - %message%newline" />
@@ -39,7 +42,7 @@ The encoding to use to write to the file is also specified.
 [source,xml]
 ----
 <appender name="FileAppender" type="log4net.Appender.FileAppender">
-  <file value="${TEMP}/log-file.txt" />
+  <file value="${TEMP}/MyApp.log" />
   <appendToFile value="true" />
   <encoding value="unicodeFFFE" />
   <layout type="log4net.Layout.PatternLayout">
@@ -53,7 +56,7 @@ This example shows how to configure the appender to use the minimal locking mode
 [source,xml]
 ----
 <appender name="FileAppender" type="log4net.Appender.FileAppender">
-  <file value="log-file.txt" />
+  <file value="MyApp.log" />
   <appendToFile value="true" />
   <lockingModel type="log4net.Appender.FileAppender+MinimalLock" />
   <layout type="log4net.Layout.PatternLayout">
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/forwardingappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/forwardingappender.adoc
@@ -18,13 +18,14 @@
 [#forwardingappender]
 = ForwardingAppender
 
+The `ForwardingAppender` forwards log messages to another appender.
+This appender is used only in special circumstances.
+
 The following example shows how to configure the `ForwardingAppender`.
 The forwarding appender allows a set of constraints to be used to decorate an appender.
 
 In this example the `ConsoleAppender` is decorated with a Threshold of level WARN. This means that an event directed to the `ConsoleAppender` directly will be logged regardless of its level, but an event directed to the `ForwardingAppender` will only be passed on to the `ConsoleAppender` if its level is WARN or higher.
 
-This appender is used only in special circumstances.
-
 [source,xml]
 ----
 <appender name="ForwardingAppender" type="log4net.Appender.ForwardingAppender" >
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/localsyslogappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/localsyslogappender.adoc
@@ -0,0 +1,52 @@
+////
+    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.
+////
+
+[#localsyslogappender]
+= LocalSyslogAppender
+
+`LocalSyslogAppender` writes messages to the local syslog service on Unix-like operating systems.
+It uses the system's native syslog daemon and does not support remote logging.
+
+The following example shows how to configure the `LocalSyslogAppender`.
+It sends all events with Level WARN or higher.
+
+[source,xml]
+----
+<appender name="LocalSyslogAppender" type="log4net.Appender.LocalSyslogAppender">
+  <layout type="log4net.Layout.PatternLayout">
+    <conversionPattern value="%date{MM/dd/yyyy HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline" />
+  </layout>
+  <threshold value="WARN" />
+</appender>
+----
+
+You can also specify:
+
+* Facility (default: user)
+* Identity (default: application name)
+
+[source,xml]
+----
+<appender name="LocalSyslogAppender" type="log4net.Appender.LocalSyslogAppender">
+  <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>
+  <threshold value="WARN" />
+</appender>
+----
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/managedcoloredconsoleappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/managedcoloredconsoleappender.adoc
@@ -18,6 +18,9 @@
 [#managedcoloredconsoleappender]
 = ManagedColoredConsoleAppender
 
+The `ManagedColoredConsoleAppender` writes log messages to the console with colored output.
+It provides more control over the colors used for different log levels.
+
 The following example shows how to configure the `ManagedColoredConsoleAppender` to log messages to the console.
 By default the messages are sent to the console standard output stream.
 
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/memoryappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/memoryappender.adoc
@@ -18,6 +18,9 @@
 [#memoryappender]
 = MemoryAppender
 
+The `MemoryAppender` stores log events in memory rather than writing them to a file or console.
+It is useful for in-memory logging and can be configured to store events until the application is stopped or the memory is cleared.
+
 It is unlikely that the `MemoryAppender` will be configured using a config file, but if you want to do it here's how.
 
 [source,xml]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/outputdebugstringappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/outputdebugstringappender.adoc
@@ -18,6 +18,9 @@
 [#outputdebugstringappender]
 = OutputDebugStringAppender
 
+The `OutputDebugStringAppender` writes log events to the Windows debugger via the `OutputDebugString` function.
+This is useful for debugging and monitoring an application without writing to files or consoles.
+
 The following example shows how to configure the `OutputDebugStringAppender` to write logging messages to the `OutputDebugString` API.
 
 [source,xml]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/remotesyslogappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/remotesyslogappender.adoc
@@ -18,8 +18,11 @@
 [#remotesyslogappender]
 = RemoteSyslogAppender
 
-The following example shows how to configure the `RemoteSyslogAppender` to send log messages to a remote syslog daemon.
-The syslog server listens on UDP port 514 by default.
+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.
 
@@ -72,6 +75,8 @@ catch (InvalidTimeZoneException e)
 }
 ----
 
+Output (with intermixed messages):
+
 [source,log]
 ----
 12/21/2024 14:07:41.508 [main] ERROR log4net.Tests - setting daylight saving time failed
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/rollingfileappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/rollingfileappender.adoc
@@ -18,16 +18,20 @@
 [#rollingfileappender]
 = RollingFileAppender
 
-The `RollingFileAppender` builds on the `FileAppender` and has the same options as that appender.
+The `RollingFileAppender` extends the functionality of the `FileAppender` by adding the ability to automatically roll over log files based on specified criteria, such as file size or time intervals.
 
-The following example shows how to configure the `RollingFileAppender` to write to the file MyApp.log.
+This appender is useful for managing log files in production environments where log data grows over time and older logs should be preserved while maintaining a manageable file size.
 
-The file written to will always be called MyApp.log because the `StaticLogFileName` param is specified.
+The following example shows how to configure the `RollingFileAppender` to write to the file `MyApp.log`.
 
-The file will be rolled based on a size constraint (`RollingStyle`).
+The file written to will always be named `MyApp.log` because the `StaticLogFileName` parameter is specified.
+
+The file will be rolled based on a size constraint (`RollingStyle`), and old log files will be archived when the size limit is reached.
 Up to 10 (`MaxSizeRollBackups`) old files of 100 KB each (`MaximumFileSize`) will be kept.
 
-These rolled files will be named: MyApp.log.1, MyApp.log.2, MyApp.log.3, etc.
+These rolled files will be named: `MyApp.log.1`, `MyApp.log.2`, `MyApp.log.3`, etc.
+
+This allows you to keep a set number of backup log files, which can be helpful for both auditing and troubleshooting, while ensuring that log file growth doesn't fill up disk space.
 
 [source,xml]
 ----
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/smtpappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/smtpappender.adoc
@@ -18,6 +18,9 @@
 [#smtpappender]
 = SmtpAppender
 
+The `SmtpAppender` sends log events via email using the Simple Mail Transfer Protocol (SMTP).
+This appender is useful for sending email notifications when certain events occur, such as errors or critical failures in your application.
+
 The following example shows how to configure the `SmtpAppender` to deliver log events via SMTP email.
 The `To`, `From`, `Subject` and `SmtpHost` are required parameters.
 This example shows how to deliver only significant events.
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/traceappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/traceappender.adoc
@@ -18,6 +18,9 @@
 [#traceappender]
 = TraceAppender
 
+The `TraceAppender` writes log events to the Trace output, which can be viewed in debuggers or other trace listeners.
+It is useful for capturing logs in applications that are being debugged or for monitoring trace-level information during runtime.
+
 The following example shows how to configure the `TraceAppender` to log messages to the https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace[System.Diagnostics.Trace] system.
 
 [source,xml]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/udpappender.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/udpappender.adoc
@@ -18,6 +18,9 @@
 [#udpappender]
 = UdpAppender
 
+The `UdpAppender` sends log events over the network using the UDP protocol.
+It is typically used to forward log messages to remote logging systems over a network.
+
 The following example shows how to configure the `UdpAppender` to send events to a `remoteAddress` on the specified `remotePort`.
 
 [source,xml]
diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
@@ -83,24 +83,24 @@ will yield the output
 |Type |Description
 
 |log4net.Layout.ExceptionLayout
-|Renders the exception text from the logging event. 
+|Renders the exception text from the logging event.
 
 |log4net.Layout.PatternLayout
-|Formats the logging event according to a flexible set of formatting flags. 
+|Formats the logging event according to a flexible set of formatting flags.
 
 |log4net.Layout.RawTimeStampLayout
 |Extracts the timestamp from the logging event.
 
 |log4net.Layout.RawUtcTimeStampLayout
-|Extracts the timestamp from the logging event in Universal Time. 
+|Extracts the timestamp from the logging event in Universal Time.
 
 |log4net.Layout.SimpleLayout
 |Formats the logging event very simply: [level] - [message]
 
 |log4net.Layout.XmlLayout
-|Formats the logging event as an XML element. 
+|Formats the logging event as an XML element.
 
-|Eventlog4net.Layout.XmlLayoutSchemaLog4j
-|Formats the logging event as an XML element that complies with the log4j event dtd. 
+|log4net.Layout.XmlLayoutSchemaLog4j
+|Formats the logging event as an XML element that complies with the log4j event dtd.
 
 |===
