This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 66851a83157cdbbc8ab914b0f3193f4910c0ac8f Author: Volkan Yazıcı <[email protected]> AuthorDate: Mon Jun 17 13:11:03 2024 +0200 Improve documentation on structured logging (#2665) --- .../antora/modules/ROOT/pages/manual/layouts.adoc | 15 ++++++++++++++- .../ROOT/partials/manual/structured-logging.adoc | 21 +++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc index b967a0781c..d546dd9a69 100644 --- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc @@ -29,10 +29,20 @@ This page will try to answer following questions: 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. +[#structured-logging] +=== Structured logging + +include::partial$manual/structured-logging.adoc[] + +Log4j strives to provide top of the class support for structured logging. +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. + +We recommend xref:manual/json-template-layout.adoc[] for structured logging purposes. + [#charset] === Character encoding -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. +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. While doing so, unless an explicit encoding configuration is stated, they use `UTF-8` by default. 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. @@ -486,6 +496,9 @@ This attribute only applies to RFC 5424 Syslog records. |The string that should be used to replace newlines within the message text |=== +RFC 5424 Layout has specialized handling for xref:manual/messages.adoc#StructuredDataMessage[`StructuredDataMessage`]s. +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. + [#SyslogLayout] === Syslog Layout diff --git a/src/site/antora/modules/ROOT/partials/manual/structured-logging.adoc b/src/site/antora/modules/ROOT/partials/manual/structured-logging.adoc new file mode 100644 index 0000000000..7bbc08a10a --- /dev/null +++ b/src/site/antora/modules/ROOT/partials/manual/structured-logging.adoc @@ -0,0 +1,21 @@ +//// + 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. +//// + +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. +This necessitates the applications to _structure_ their logs in a machine-readable way ready to be delivered to an external system. +This act of encoding logs following a certain structure is called *structured logging*. +
