(logging-log4j2) 08/13: Add a performance section to JTL and PL

[vy...@apache.org]

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ı <vo...@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]