Skip to content

Commit 66851a8

Browse files
committed
Improve documentation on structured logging (#2665)
1 parent 82e8392 commit 66851a8

File tree

2 files changed

+35
-1
lines changed

2 files changed

+35
-1
lines changed

src/site/antora/modules/ROOT/pages/manual/layouts.adoc

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,20 @@ This page will try to answer following questions:
2929
3030
This section introduces you to some common concerns shared by almost all <<collection,predefined layouts>> that you need to be aware of while using them.
3131
32+
[#structured-logging]
33+
=== Structured logging
34+
35+
include::partial$manual/structured-logging.adoc[]
36+
37+
Log4j strives to provide top of the class support for structured logging.
38+
To create an end-to-end experience, it provides several xref:manual/messages.adoc#collection-structured[structured message types] along with layouts supporting structured logging.
39+
40+
We recommend xref:manual/json-template-layout.adoc[] for structured logging purposes.
41+
3242
[#charset]
3343
=== Character encoding
3444
35-
All <<collection[predefined layouts] produce `String` that eventually get converted into a `byte>>` using the https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html[`Charset`] configured.
45+
All <<collection,predefined layouts>> produce `String` that eventually get converted into a `byte` using the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/nio/charset/Charset.html[`Charset`] configured.
3646
While doing so, unless an explicit encoding configuration is stated, they use `UTF-8` by default.
3747
If you want all your log events to be formatted in a certain character encoding that is different from what the employed layout defaults to, make sure to configure the layout's character encoding as needed.
3848
@@ -486,6 +496,9 @@ This attribute only applies to RFC 5424 Syslog records.
486496
|The string that should be used to replace newlines within the message text
487497
|===
488498
499+
RFC 5424 Layout has specialized handling for xref:manual/messages.adoc#StructuredDataMessage[`StructuredDataMessage`]s.
500+
By combining two, users can have complete control on how their message is encoded in a way compliant with RFC 5424, while RFC 5424 Layout will make sure the rest of the information attached to the log event is properly injected.
501+
489502
[#SyslogLayout]
490503
=== Syslog Layout
491504
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
////
2+
Licensed to the Apache Software Foundation (ASF) under one or more
3+
contributor license agreements. See the NOTICE file distributed with
4+
this work for additional information regarding copyright ownership.
5+
The ASF licenses this file to You under the Apache License, Version 2.0
6+
(the "License"); you may not use this file except in compliance with
7+
the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
////
17+
18+
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.
19+
This necessitates the applications to _structure_ their logs in a machine-readable way ready to be delivered to an external system.
20+
This act of encoding logs following a certain structure is called *structured logging*.
21+

0 commit comments

Comments
 (0)