Skip to content

Commit 86f7a84

Browse files
FreeAndNilFreeAndNil
committed
updated config examples
1 parent d63a1c5 commit 86f7a84

File tree

1 file changed

+66
-195
lines changed

1 file changed

+66
-195
lines changed

‎src/site/antora/modules/ROOT/pages/manual/configuration-examples.adoc‎

Lines changed: 66 additions & 195 deletions
Original file line numberDiff line numberDiff line change
@@ -15,220 +15,91 @@
1515
limitations under the License.
1616
////
1717
18-
[#configuration]
19-
= Configuration
18+
[#config-examples]
19+
= Config Examples
2020
21-
Using a configuration file is the most popular and recommended approach for configuring log4net.
22-
In this page we will examine the composition of a configuration file and how log4net uses it.
21+
This document presents example configurations for the built-in appenders. These configurations are designed to work with the log4net.Config.XmlConfigurator.
2322
24-
[source,csharp]
25-
----
26-
using Animals.Carnivora;
27-
// Import log4net classes.
28-
using log4net;
29-
using log4net.Config;
30-
31-
namespace SampleApp;
32-
33-
private static class MyApp
34-
{
35-
// Define a static logger variable so that it references the Logger instance named "MyApp".
36-
private static readonly ILog logger = LogManager.GetLogger(typeof(MyApp));
37-
38-
private static void Main(string[] args)
39-
{
40-
// Set up a simple configuration that logs on the console.
41-
BasicConfigurator.Configure();
42-
43-
logger.Info("Entering application.");
44-
Dog dog = new();
45-
bar.Bark();
46-
logger.Info("Exiting application.");
47-
}
48-
}
49-
----
50-
51-
MyApp begins by importing log4net related namespaces.
52-
It then defines a static logger variable with the name MyApp which happens to be the fully qualified name of the class.
53-
54-
MyApp uses the following Dog class:
55-
56-
[source,csharp]
57-
----
58-
59-
// Import log4net classes
60-
using log4net;
61-
62-
namespace Animals.Carnivora;
63-
64-
internal sealed class Dog
65-
{
66-
private static readonly ILog logger = LogManager.GetLogger(typeof(Dog));
23+
These examples are by no means exhaustive configurations for the appenders.
6724
68-
internal void Bark() => logger.Debug("Woof!");
69-
}
70-
----
25+
[#adonetappender]
26+
== AdoNetAppender
7127
72-
The invocation of the BasicConfigurator.Configure() method creates a rather simple log4net setup.
73-
This method is hardwired to add to the root logger a ConsoleAppender.
74-
The output will be formatted using a PatternLayout set to the following pattern:
28+
The configuration of the AdoNetAppender depends on the provider selected for the target database. Here are some examples.
7529
76-
[source,log]
77-
----
78-
%timestamp [%thread] %level %logger %ndc - %message%newline
79-
----
30+
[#mssqlserver]
31+
=== MS SQL Server
8032
81-
Note that by default, the root logger is assigned to Level.DEBUG.
33+
The following example shows how to configure the AdoNetAppender to log messages to a SQL Server database. 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.
8234
83-
The output of MyApp is:
35+
The database table definition is:
8436
85-
[source,log]
86-
----
87-
2024-12-21 14:07:41,508 [main] INFO SampleApp.MyApp - Entering application.
88-
2024-12-21 14:07:41,517 [main] DEBUG Animals.Carnivora.Dog - Woof!
89-
2024-12-21 14:07:41,529 [main] INFO SampleApp.MyApp - Exiting application.
37+
[source,sql]
9038
----
91-
92-
As a side note, let me mention that in log4net child loggers link only to their existing ancestors.
93-
In particular, the logger named Animals.Carnivora.Dog is linked directly to the root logger, thereby circumventing the unused Animals or Animals.Carnivora loggers.
94-
This significantly increases performance and reduces log4net's memory footprint.
95-
96-
The MyApp class configures log4net by invoking BasicConfigurator.Configure() method.
97-
Other classes only need to import the log4net namespace, retrieve the loggers they wish to use, and log away.
98-
99-
The previous example always outputs the same log information.
100-
Fortunately, it is easy to modify MyApp so that the log output can be controlled at run-time.
101-
Here is a slightly modified version.
102-
103-
[source,csharp]
104-
----
105-
using Animals.Carnivora;
106-
// Import log4net classes.
107-
using log4net;
108-
using log4net.Config;
109-
110-
namespace SampleApp;
111-
112-
private static class MyApp
113-
{
114-
private static readonly ILog logger = LogManager.GetLogger(typeof(MyApp));
115-
116-
private static void Main(string[] args)
117-
{
118-
// BasicConfigurator replaced with XmlConfigurator.
119-
XmlConfigurator.Configure();
120-
121-
logger.Info("Entering application.");
122-
Dog dog = new();
123-
bar.Bark();
124-
logger.Info("Exiting application.");
125-
}
126-
}
39+
create table dbo.Log
40+
(
41+
Id bigint identity (1, 1) not null,
42+
LogDate datetime not null,
43+
Thread nvarchar(255) not null,
44+
LogLevel nvarchar(50) not null,
45+
Logger nvarchar(255) not null,
46+
LogMessage nvarchar(2000) not null,
47+
Exception nvarchar(2000) null,
48+
constraint Log_PKEY primary key (Id)
49+
) with (data_compression = page)
12750
----
12851
129-
This version of MyApp instructs the XmlConfigurator to parse a configuration file and set up logging accordingly.
130-
131-
Here is a sample configuration file that results in exactly same output as the previous BasicConfigurator based example.
52+
The appender configuration is:
13253
13354
[source,xml]
13455
----
135-
<log4net>
136-
<!-- ConsoleAppender is set to be a ConsoleAppender -->
137-
<appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
138-
<!-- ConsoleAppender uses PatternLayout -->
56+
<appender name="AdoNetAppender" type="log4net.Appender.AdoNetAppender">
57+
<bufferSize value="100"/>
58+
<connectionType value="System.Data.SqlClient.SqlConnection, System.Data"/>
59+
<connectionString value="data source=[database server];initial catalog=[database name];integrated security=false;persist security info=True;User ID=[user];Password=[password]"/>
60+
<commandText value="insert into dbo.Log (LogDate, Thread, LogLevel, Logger, LogMessage, Exception) values (@LogDate, @Thread, @LogLevel, @Logger, @LogMessage, @Exception)"/>
61+
<parameter>
62+
<parameterName value="@LogDate"/>
63+
<dbType value="DateTime"/>
64+
<layout type="log4net.Layout.RawTimeStampLayout"/>
65+
</parameter>
66+
<parameter>
67+
<parameterName value="@Thread"/>
68+
<dbType value="String"/>
69+
<size value="255"/>
13970
<layout type="log4net.Layout.PatternLayout">
140-
<conversionPattern value="%-4timestamp [%thread] %-5level %logger %ndc - %message%newline" />
71+
<conversionPattern value="%thread"/>
14172
</layout>
142-
</appender>
143-
<!-- Set root logger level to DEBUG and its only appender to ConsoleAppender -->
144-
<root>
145-
<level value="DEBUG" />
146-
<appender-ref ref="ConsoleAppender" />
147-
</root>
148-
</log4net>
149-
----
150-
151-
Suppose we are no longer interested in seeing the output of any component belonging to the Animals.Carnivora namespace.
152-
153-
The following configuration file shows one possible way of achieving this.
154-
155-
[source,xml]
156-
----
157-
<log4net>
158-
<!-- ConsoleAppender is set to be a ConsoleAppender -->
159-
<appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
160-
<!-- ConsoleAppender uses PatternLayout -->
73+
</parameter>
74+
<parameter>
75+
<parameterName value="@LogLevel"/>
76+
<dbType value="String"/>
77+
<size value="50"/>
16178
<layout type="log4net.Layout.PatternLayout">
162-
<conversionPattern value="%-4timestamp [%thread] %-5level %logger %ndc - %message%newline" />
79+
<conversionPattern value="%level"/>
16380
</layout>
164-
</appender>
165-
<!-- Set root logger level to DEBUG and its only appender to ConsoleAppender -->
166-
<root>
167-
<level value="DEBUG" />
168-
<appender-ref ref="ConsoleAppender" />
169-
</root>
170-
<!-- Print only messages of level WARN or above in the namespace Animals.Carnivora -->
171-
<logger name="Animals.Carnivora">
172-
<level value="WARN" />
173-
</logger>
174-
</log4net>
175-
----
176-
177-
The output of MyApp configured with this file is shown below.
178-
179-
[source,log]
180-
----
181-
2024-12-21 14:07:41,508 [main] INFO SampleApp.MyApp - Entering application.
182-
2024-12-21 14:07:41,529 [main] INFO SampleApp.MyApp - Exiting application.
183-
----
184-
185-
As the logger Animals.Carnivora.Dog does not have an assigned level, it inherits its level from Animals.Carnivora, which was set to WARN in the configuration file.
186-
The log statement from the Dog.Bark method has the level DEBUG, lower than the logger level WARN.
187-
Consequently, Bark() method's log request is suppressed.
188-
189-
Here is another configuration file that uses multiple appenders.
190-
191-
[source,xml]
192-
----
193-
<log4net>
194-
<appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
81+
</parameter>
82+
<parameter>
83+
<parameterName value="@Logger"/>
84+
<dbType value="String"/>
85+
<size value="255"/>
19586
<layout type="log4net.Layout.PatternLayout">
196-
<!-- Pattern to output the caller's file name and line number -->
197-
<conversionPattern value="%5level [%thread] (%file:%line) - %message%newline" />
87+
<conversionPattern value="%logger"/>
19888
</layout>
199-
</appender>
200-
<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
201-
<file value="example.log" />
202-
<appendToFile value="true" />
203-
<maximumFileSize value="100KB" />
204-
<maxSizeRollBackups value="2" />
89+
</parameter>
90+
<parameter>
91+
<parameterName value="@LogMessage"/>
92+
<dbType value="String"/>
93+
<size value="2000"/>
20594
<layout type="log4net.Layout.PatternLayout">
206-
<conversionPattern value="%level %thread %logger - %message%newline" />
95+
<conversionPattern value="%message"/>
20796
</layout>
208-
</appender>
209-
<!-- Set root logger level to DEBUG and its only appender to ConsoleAppender -->
210-
<root>
211-
<level value="DEBUG" />
212-
<appender-ref ref="ConsoleAppender" />
213-
<appender-ref ref="RollingFile" />
214-
</root>
215-
</log4net>
216-
----
217-
218-
Calling the enhanced MyApp with the this configuration file will output the following on the console.
219-
220-
[source,log]
221-
----
222-
INFO [main] (MyApp.cs:17) - Entering application.
223-
DEBUG [main] (Dog.cs:10) - Woof!
224-
INFO [main] (MyApp.cs:20) - Exiting application.
225-
----
226-
227-
In addition, as the root logger has been allocated a second appender, output will also be directed to the example.log file.
228-
This file will be rolled over when it reaches 100KB.
229-
When roll-over occurs, the old version of example.log is automatically moved to example.log.1.
230-
231-
Note that to obtain these different logging behaviors we did not need to recompile code.
232-
We could just as easily have logged to an email address or redirected all Animals.Carnivora output to an remote syslog server.
233-
234-
For more examples of configuring appenders using the XmlConfigurator see the Example Appender Configuration #TODO document.
97+
</parameter>
98+
<parameter>
99+
<parameterName value="@Exception"/>
100+
<dbType value="String"/>
101+
<size value="2000"/>
102+
<layout type="log4net.Layout.ExceptionLayout"/>
103+
</parameter>
104+
</appender>
105+
----

0 commit comments

Comments
 (0)