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]