This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch doc/perf-main
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 379cbe70c0364c8e962120e846b1ee6205402136
Author: Volkan Yazıcı <vol...@yazi.ci>
AuthorDate: Tue May 14 15:59:24 2024 +0200
Add a performance section to JTL and PL
---
.../ROOT/pages/manual/json-template-layout.adoc | 32 ++++++++++++++++------
.../antora/modules/ROOT/pages/manual/layouts.adoc | 10 +++++++
.../modules/ROOT/pages/manual/performance.adoc | 4 +--
3 files changed, 36 insertions(+), 10 deletions(-)
diff --git
a/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
index c672912fcd..7b91e4474b 100644
--- a/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
@@ -212,7 +212,7 @@ appender.console.layout.eventTemplateUri =
classpath:EcsLayout.json
separating rendered ``LogEvent``s (defaults to `false` set by
`log4j.layout.jsonTemplate.nullEventDelimiterEnabled` property)
-| maxStringLength
+| [[maxStringLength]] maxStringLength
| int
| truncate string values longer than the specified limit (defaults to 16384 set
by `log4j.layout.jsonTemplate.maxStringLength` property)
@@ -383,7 +383,7 @@ Event template resolvers consume a `LogEvent` and render a
certain property of
it at the point of the JSON where they are declared. For instance, `marker`
resolver renders the marker of the event, `level` resolver renders the level,
and so on. An event template resolver is denoted with a special object
-containing a`$resolver` key:
+containing a `$resolver` key:
.Example event template demonstrating the usage of `level` resolver
[source,json]
@@ -397,9 +397,8 @@ containing a`$resolver` key:
}
----
-Here `version` field will be rendered as is, while `level` field will be
-populated by the `level` resolver. That is, this template will generate JSON
-similar to the following:
+Here `version` field will be rendered as is, while `level` field will be
populated by xref:#event-template-resolver-level[the `level` resolver].
+That is, this template will generate JSON similar to the following:
.Example JSON generated from the demonstrated event template
[source,json]
@@ -1158,6 +1157,13 @@ Resolves the fields of the `StackTraceElement` returned
by
Note that this resolver is toggled by
`log4j.layout.jsonTemplate.locationInfoEnabled` property.
+[WARNING]
+====
+Mind that capturing the source location information is an expensive operation,
and is not garbage-free.
+Note that xref:#event-template-resolver-logger[the `logger` resolver] can
generally be used as a zero-cost substitute for `className`.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts
page] for details.
+====
+
====== Examples
Resolve the line number:
@@ -1846,6 +1852,17 @@ alternatives.
| ✕
|===
+[#performance]
+== Performance
+
+JSON Template Layout is a heavily optimized piece of software to encode a log
event as fast as possible.
+To get the most out of it, mind the following checklist:
+
+* Enable xref:manual/garbagefree.adoc[garbage-free logging]
+* Mind xref:#faq-garbage-free[the garbage footprint of features you use]
+* Choose a xref:#recycling-strategy[recycling strategy] that suits best to
your deployment environment
+* Don't give too much slack to xref:#maxStringLength[`maxStringLength`] and
try to keep it relatively tight
+
[#faq]
== F.A.Q.
@@ -1875,9 +1892,8 @@ logging.
[#faq-garbage-free]
=== Is `JsonTemplateLayout` garbage-free?
-Yes, if the garbage-free layout behaviour toggling properties
-`log4j2.enableDirectEncoders` and `log4j2.garbagefreeThreadContextMap` are
-enabled. Take into account the following caveats:
+Yes, if xref:manual/garbagefree.adoc[garbage-free logging] is enabled.
+Take into account the following caveats:
* The configured recycling strategy might not be
garbage-free.
diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
index dce83f99ea..dfb13d384e 100644
--- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
@@ -1792,6 +1792,16 @@ information
* %u, %uuid - Creates a new random or time-based UUID while formatting
====
+[#PatternLayout-performance]
+=== Performance
+
+Great effort has been put into the efficiency of Pattern Layout.
+To get the most out of it, mind the following checklist:
+
+* Enable xref:manual/garbagefree.adoc[garbage-free logging]
+* Mind xref:#PatternLayout-gcfree[the garbage footprint of features you use]
+* Don't give too much slack to
xref:manual/configuration.adoc#log4j2.layoutStringBuilderMaxSize[`log4j2.layoutStringBuilderMaxSize`]
and try to keep it relatively tight
+
[#RFC5424Layout]
== RFC5424 Layout
diff --git a/src/site/antora/modules/ROOT/pages/manual/performance.adoc
b/src/site/antora/modules/ROOT/pages/manual/performance.adoc
index cced659d63..3ea2e59eea 100644
--- a/src/site/antora/modules/ROOT/pages/manual/performance.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/performance.adoc
@@ -130,11 +130,11 @@
include::partial$manual/layouts-location-information.adoc[]
Not all layouts are designed with the same performance considerations in mind.
Following layouts are known to be well-optimized for performance-sensitive
workloads:
-xref:manual/json-template-layout.adoc[JSON Template Layout]::
+xref:manual/json-template-layout.adoc#performance[JSON Template Layout]::
It encodes log events into JSON according to the structure described by the
template provided.
Its output can safely be ingested into several log storage solutions:
Elasticsearch, Google Cloud Logging, Graylog, Logstash, etc.
-xref:manual/layouts.adoc#PatternLayout[Pattern Layout]::
+xref:manual/layouts.adoc#PatternLayout-performance[Pattern Layout]::
It encodes log events into human-readable text according to the pattern
provided.
[#async]
