You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/site/antora/modules/ROOT/pages/manual/layouts.adoc
+62-36Lines changed: 62 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,41 +25,45 @@ This page will try to answer following questions:
25
25
* <<extending,How can you create custom layouts?>>
26
26
27
27
[#concerns]
28
-
== Common concerns
28
+
== Common Concerns
29
29
30
-
This section introduces you to some common concerns shared by almost all predefined layouts that you need to be aware of while using them.
30
+
This section outlines some common concerns shared by most predefined layouts in log4net that users should be aware of.
31
31
32
32
[#structured-logging]
33
-
=== Structured logging
33
+
=== Structured Logging
34
34
35
-
In almost any modern production deployment, logs are no more written to files read by engineers while troubleshooting, but forwarded to log ingestion systems (Elasticsearch, Google Cloud Logging, etc.) for several observability use cases ranging from logging to metrics.
36
-
This necessitates the applications to _structure_ their logs in a machine-readable way ready to be delivered to an external system.
37
-
This act of encoding logs following a certain structure is called *structured logging*.
35
+
In modern production environments, logs are typically not read from local files by engineers.
36
+
Instead, they are sent to log ingestion systems like Elasticsearch, Google Cloud Logging, or similar platforms for observability, metrics, and monitoring purposes.
38
37
39
-
log4net tries to provide good support for structured logging.
40
-
To create an end-to-end experience, it provides several layouts supporting structured logging.
38
+
To support this, logs must be encoded in a machine-readable format — a practice known as *structured logging*.
41
39
42
-
We recommend XmlLayout or https://gitlab.com/gdziadkiewicz/log4net.Ext.Json/-/blob/develop/log4net.Ext.Json/Layout/SerializedLayout.cs[JsonLayout] for structured logging purposes.
40
+
log4net provides support for structured logging through specialized layouts.
41
+
For production use cases, we recommend using either:
43
42
44
-
[#collection]
45
-
== Collection
43
+
* `XmlLayout` — for structured XML output.
44
+
* `JsonLayout` — via the external project https://gitlab.com/gdziadkiewicz/log4net.Ext.Json/-/blob/develop/log4net.Ext.Json/Layout/SerializedLayout.cs[log4net.Ext.Json].
46
45
47
-
log4net bundles predefined layouts to assist in several common deployment use cases.
46
+
These layouts help ensure your logs are compatible with log aggregation and analysis tools.
48
47
49
-
[id=pattern-layout]
50
-
=== [[PatternLayout]] Pattern Layout
48
+
[#predefined-layouts]
49
+
== Predefined Layouts
51
50
52
-
`PatternLayout` is a customizable, efficient, garbage-free, and human-readable string generating layout using a user-provided pattern.
53
-
It is analogous to `String.Format()` with specialized directives on injecting certain properties of a `LogEvent`.
51
+
log4net includes a set of predefined layouts designed to support a variety of common logging scenarios.
52
+
53
+
[#patternlayout]
54
+
=== PatternLayout
55
+
56
+
`PatternLayout` is a customizable, efficient, and human-readable layout that generates log messages based on a user-defined pattern.
57
+
It works similarly to `String.Format()` but provides specialized directives for injecting properties from a `LoggingEvent`.
54
58
55
59
[IMPORTANT]
56
60
====
57
-
Pattern Layout is not intended for _structural logging_ purposes.
58
-
For production environments, you are strongly advised to use XmlLayout or JsonLayout producing XML/JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
61
+
`PatternLayout` is *not* intended for structured logging.
62
+
In production, prefer `XmlLayout` or `JsonLayout` for generating machine-readable logs (e.g., XML or JSON) that can be consumed by log ingestion systems such as Elasticsearch or Google Cloud Logging.
59
63
====
60
64
61
-
A conversion pattern is composed of literal text and format control expressions.
62
-
For instance, given the `%timestamp [%thread] %-5level %logger - %message%newline` pattern, following statements
65
+
A conversion pattern is composed of literal text and conversion specifiers (format control expressions).
The `DynamicPatternLayout` should be used whenever the header or footer needs to include information that may change over time.
86
+
87
+
Unlike the static `PatternLayout`, which renders headers and footers only once, the `DynamicPatternLayout` re-evaluates its pattern every time it is invoked.
88
+
This makes it possible, for example, to include the current date and time in the header or footer—something not possible with the static layout.
89
+
90
+
The following example shows how to configure the `DynamicPatternLayout`:
|Renders the exception text from the logging event.
108
+
|`log4net.Layout.DynamicPatternLayout`
109
+
|Formats the logging event using a pattern string that is re-evaluated on every log event, allowing dynamic values like timestamps in headers or footers.
110
+
111
+
|`log4net.Layout.ExceptionLayout`
112
+
|Outputs only the exception text from the logging event.
87
113
88
-
|log4net.Layout.PatternLayout
89
-
|Formats the logging event according to a flexible set of formatting flags.
114
+
|`log4net.Layout.PatternLayout`
115
+
|Formats the logging event using a flexible pattern string with various conversion specifiers.
90
116
91
-
|log4net.Layout.RawTimeStampLayout
92
-
|Extracts the timestamp from the logging event.
117
+
|`log4net.Layout.RawTimeStampLayout`
118
+
|Outputs the raw timestamp (as a `DateTime`) from the logging event.
93
119
94
-
|log4net.Layout.RawUtcTimeStampLayout
95
-
|Extracts the timestamp from the logging event in Universal Time.
120
+
|`log4net.Layout.RawUtcTimeStampLayout`
121
+
|Outputs the raw timestamp in UTC from the logging event.
96
122
97
-
|log4net.Layout.SimpleLayout
98
-
|Formats the logging event very simply: [level] - [message]
123
+
|`log4net.Layout.SimpleLayout`
124
+
|Provides a very simple format: `[level] - [message]`.
99
125
100
-
|log4net.Layout.XmlLayout
101
-
|Formats the logging event as an XML element.
126
+
|`log4net.Layout.XmlLayout`
127
+
|Formats the logging event as a basic XML element.
102
128
103
-
|log4net.Layout.XmlLayoutSchemaLog4j
104
-
|Formats the logging event as an XML element that complies with the log4j event dtd.
129
+
|`log4net.Layout.XmlLayoutSchemaLog4j`
130
+
|Formats the logging event as XML compliant with the log4j event DTD.
0 commit comments