Implement log4j compatibility mode

Author: 0xced

README.md

@@ -107,6 +107,22 @@ By default, Log4NetTextFormatter serializes all Serilog properties. You can filt
 new Log4NetTextFormatter(c => c.UsePropertyFilter((_, name) => name != "MySecretProperty"))
 ```
 
+#### Log4j compatibility mode
+
+The formatter also supports a log4j compatibility mode. Log4Net and Log4j XML formats are very similar but have a few key differences.
+
+* Events are in different XML namespaces
+* The `timestamp` is a number of milliseconds (log4j) vs an ISO 8061 formatted date (log4net)
+* Exception elements are named `throwable` vs `exception`
+
+In order to enable the compatibility mode, call `UseLog4JCompatibility()`:
+
+```c#
+new Log4NetTextFormatter(c => c.UseLog4JCompatibility())
+```
+
+Note that unlike other fluent configuration methods, this one can not be chained because you should not change options after enabling the log4j compatibility mode.
+
 ### Combining options
 
 You can also combine options, for example, both removing namespaces and using Ben.Demystifier for exception formatting:

src/Log4NetTextFormatter.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
 using System.IO;
 using System.Linq;
 using System.Xml;
@@ -89,9 +90,11 @@ public void Format(LogEvent logEvent, TextWriter output)
         /// <remarks>https://github.com/apache/logging-log4net/blob/rel/2.0.8/src/Layout/XmlLayout.cs#L218-L310</remarks>
         private void WriteEvent(LogEvent logEvent, XmlWriter writer)
         {
+            var useLog4JCompatibility = _options.Log4NetXmlNamespace?.Name == "log4j";
             WriteStartElement(writer, "event");
             WriteEventAttribute(logEvent, writer, "logger", Constants.SourceContextPropertyName);
-            writer.WriteAttributeString("timestamp", XmlConvert.ToString(logEvent.Timestamp));
+            var timestamp = useLog4JCompatibility ? logEvent.Timestamp.ToUnixTimeMilliseconds().ToString(CultureInfo.InvariantCulture) : XmlConvert.ToString(logEvent.Timestamp);
+            writer.WriteAttributeString("timestamp", timestamp);
             writer.WriteAttributeString("level", LogLevel(logEvent.Level));
             WriteEventAttribute(logEvent, writer, "thread", ThreadIdPropertyName);
             WriteDomainAndUserName(logEvent, writer);
@@ -102,7 +105,7 @@ private void WriteEvent(LogEvent logEvent, XmlWriter writer)
                 WriteProperties(logEvent, writer, properties, machineNameProperty);
             }
             WriteMessage(logEvent, writer);
-            WriteException(logEvent, writer);
+            WriteException(logEvent, writer, useLog4JCompatibility ? "throwable" : "exception");
             writer.WriteEndElement();
         }
 
@@ -146,16 +149,17 @@ private void WriteEventAttribute(LogEvent logEvent, XmlWriter writer, string att
         }
 
         /// <summary>
-        /// Convert Serilog <see cref="LogEventLevel"/> into log4net equivalent level.
+        /// Convert Serilog <see cref="LogEventLevel"/> into log4net/log4j equivalent level.
         /// </summary>
         /// <param name="level">The serilog level.</param>
-        /// <returns>The equivalent log4net level.</returns>
+        /// <returns>The equivalent log4net/log4j level.</returns>
         /// <remarks>https://github.com/apache/logging-log4net/blob/rel/2.0.8/src/Core/Level.cs#L509-L603</remarks>
+        /// <remarks>https://github.com/apache/log4j/blob/v1_2_17/src/main/java/org/apache/log4j/Level.java#L48-L92</remarks>
         private static string LogLevel(LogEventLevel level)
         {
             return level switch
             {
-                LogEventLevel.Verbose => "VERBOSE",
+                LogEventLevel.Verbose => "TRACE",
                 LogEventLevel.Debug => "DEBUG",
                 LogEventLevel.Information => "INFO",
                 LogEventLevel.Warning => "WARN",
@@ -331,9 +335,10 @@ private void WriteMessage(LogEvent logEvent, XmlWriter writer)
         /// </summary>
         /// <param name="logEvent">The log event.</param>
         /// <param name="writer">The XML writer.</param>
+        /// <param name="elementName">The element name, should be either <c>exception</c> or <c>throwable</c>.</param>
         /// <remarks>https://github.com/apache/logging-log4net/blob/rel/2.0.8/src/Layout/XmlLayout.cs#L288-L295</remarks>
         [SuppressMessage("Microsoft.Design", "CA1031", Justification = "Protecting from user-provided code which might throw anything")]
-        private void WriteException(LogEvent logEvent, XmlWriter writer)
+        private void WriteException(LogEvent logEvent, XmlWriter writer, string elementName)
         {
             var exception = logEvent.Exception;
             if (exception == null)
@@ -352,7 +357,7 @@ private void WriteException(LogEvent logEvent, XmlWriter writer)
             }
             if (formattedException != null)
             {
-                WriteContent(writer, "exception", formattedException);
+                WriteContent(writer, elementName, formattedException);
             }
         }
 

src/Log4NetTextFormatterOptionsBuilder.cs

@@ -151,6 +151,31 @@ public Log4NetTextFormatterOptionsBuilder UseExceptionFormatter(ExceptionFormatt
             return this;
         }
 
+        /// <summary>
+        /// Enables log4j compatibility mode. This tweaks the XML elements to match the log4j logging event specification.
+        /// The DTD can be found at https://raw.githubusercontent.com/apache/log4j/v1_2_17/src/main/resources/org/apache/log4j/xml/log4j.dtd
+        /// <para>
+        /// Here is the list of differences between the log4net and the log4j XML layout:
+        /// <list type="bullet">
+        ///   <item>The log element uses <c>log4j</c> instead of <c>log4net</c> XML namespace.</item>
+        ///   <item>The <c>timestamp</c> attribute uses milliseconds elapsed from 1/1/1970 instead of an ISO 8601 formatted date.</item>
+        ///   <item>The exception element is named <c>throwable</c> instead of <c>exception</c>.</item>
+        /// </list>
+        /// </para>
+        /// </summary>
+        /// <remarks>You must not change other options after calling this method.</remarks>
+        public void UseLog4JCompatibility()
+        {
+            // https://github.com/apache/log4j/blob/v1_2_17/src/main/java/org/apache/log4j/xml/XMLLayout.java#L135
+            LineEnding = LineEnding.CarriageReturn | LineEnding.LineFeed;
+
+            // https://github.com/apache/log4j/blob/v1_2_17/src/main/java/org/apache/log4j/xml/XMLLayout.java#L137
+            Log4NetXmlNamespace = new XmlQualifiedName("log4j", "http://jakarta.apache.org/log4j/");
+
+            // https://github.com/apache/log4j/blob/v1_2_17/src/main/java/org/apache/log4j/xml/XMLLayout.java#L147
+            CDataMode = CDataMode.Always;
+        }
+
         internal Log4NetTextFormatterOptions Build()
             => new Log4NetTextFormatterOptions(FormatProvider, CDataMode, Log4NetXmlNamespace, CreateXmlWriterSettings(LineEnding, IndentationSettings), FilterProperty, FormatException);
 

tests/Log4NetTextFormatterOptionsBuilderTest.cs

@@ -120,6 +120,22 @@ public void UseExceptionFormatter()
             builder.FormatException.Should().BeSameAs(formatException);
         }
 
+        [Fact]
+        public void UseLog4JCompatibility()
+        {
+            // Arrange
+            var builder = new Log4NetTextFormatterOptionsBuilder();
+
+            // Act
+            builder.UseLog4JCompatibility();
+
+            // Assert
+            builder.LineEnding.Should().Be(LineEnding.CarriageReturn | LineEnding.LineFeed);
+            builder.CDataMode.Should().Be(CDataMode.Always);
+            builder.Log4NetXmlNamespace.Should().NotBeNull();
+            builder.Log4NetXmlNamespace!.Name.Should().Be("log4j");
+        }
+
         [Fact]
         public void SettingExceptionFormatterToNullThrowsArgumentNullException()
         {

tests/Log4NetTextFormatterTest.Log4JCompatibility.approved.xml

@@ -0,0 +1,8 @@
+<log4j:event timestamp="1041689366535" level="INFO" xmlns:log4j="http://jakarta.apache.org/log4j/">
+  <log4j:properties>
+    <log4j:data name="π" value="3.14" />
+  </log4j:properties>
+  <log4j:message><![CDATA[Hello from Serilog]]></log4j:message>
+  <log4j:throwable><![CDATA[System.Exception: An error occurred
+  at Serilog.Formatting.Log4Net.Tests.Log4NetTextFormatterTest.BasicMessage_WithException() in Log4NetTextFormatterTest.cs:123]]></log4j:throwable>
+</log4j:event>

tests/Log4NetTextFormatterTest.LogEventLevel.Verbose.approved.xml

@@ -1,3 +1,3 @@
-<log4net:event timestamp="2003-01-04T15:09:26.535+01:00" level="VERBOSE" xmlns:log4net="http://logging.apache.org/log4net/schemas/log4net-events-1.2/">
+<log4net:event timestamp="2003-01-04T15:09:26.535+01:00" level="TRACE" xmlns:log4net="http://logging.apache.org/log4net/schemas/log4net-events-1.2/">
   <log4net:message><![CDATA[Hello from Serilog]]></log4net:message>
 </log4net:event>

tests/Log4NetTextFormatterTest.cs

@@ -118,6 +118,21 @@ public void InvalidLogEventLevelThrowsArgumentOutOfRangeException()
                 .And.Message.Should().StartWith("The value of argument 'level' (-1) is invalid for enum type 'LogEventLevel'.");
         }
 
+        [Fact]
+        public void InvalidLogEventLevelWithLog4JCompatibilityThrowsArgumentOutOfRangeException()
+        {
+            // Arrange
+            var logEvent = CreateLogEvent((LogEventLevel)(-1));
+            var formatter = new Log4NetTextFormatter(c => c.UseLog4JCompatibility());
+
+            // Act
+            Action action = () => formatter.Format(logEvent, TextWriter.Null);
+
+            // Assert
+            action.Should().ThrowExactly<ArgumentOutOfRangeException>()
+                .And.Message.Should().StartWith("The value of argument 'level' (-1) is invalid for enum type 'LogEventLevel'.");
+        }
+
         [Theory]
         [InlineData(Log4Net.CDataMode.Always, true)]
         [InlineData(Log4Net.CDataMode.Always, false)]
@@ -258,6 +273,24 @@ public void DefaultFormatProvider()
             Approvals.VerifyWithExtension(output.ToString(), "xml");
         }
 
+        [Fact]
+        public void Log4JCompatibility()
+        {
+            // Arrange
+            using var output = new StringWriter();
+            var logEvent = CreateLogEvent(
+                exception: new Exception("An error occurred").SetStackTrace(@"  at Serilog.Formatting.Log4Net.Tests.Log4NetTextFormatterTest.BasicMessage_WithException() in Log4NetTextFormatterTest.cs:123"),
+                properties: new LogEventProperty("π", new ScalarValue(3.14m))
+            );
+            var formatter = new Log4NetTextFormatter(c => c.UseLog4JCompatibility());
+
+            // Act
+            formatter.Format(logEvent, output);
+
+            // Assert
+            Approvals.VerifyWithExtension(output.ToString(), "xml");
+        }
+
         [Fact]
         public void ExplicitFormatProvider()
         {