ppkarwasz commented on code in PR #2736:
URL: https://github.com/apache/logging-log4j2/pull/2736#discussion_r1679153884
##########
src/site/antora/modules/ROOT/pages/manual/lookups.adoc:
##########
@@ -16,69 +16,361 @@
////
= Lookups
-Lookups provide a way to add values to the Log4j configuration at
-arbitrary places. They are a particular type of Plugin that implements
-the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
-interface. Information on how to use Lookups in configuration files can
-be found in the xref:manual/configuration.adoc#PropertySubstitution[Property
-Substitution] section of the xref:manual/configuration.adoc[Configuration]
-page.
+Log4j Core provides a flexible and extensible property substitution system.
-[#ContextMapLookup]
-== Context Map Lookup
+[#StrSubstitutor-diagram]
+.Property substitution system
+[plantuml]
+....
+@startuml
+class StrSubstitutor #line.bold {
+ Interpolator interpolator
+ String replace(String input)
+ String replace(LogEvent event, String input)
+}
-The ContextMapLookup allows applications to store data in the Log4j
-ThreadContext Map and then retrieve the values in the Log4j
-configuration. In the example below, the application would store the
-current user's login id in the ThreadContext Map with the key "loginId".
-During initial configuration processing the first '$' will be removed.
-The PatternLayout supports interpolation with Lookups and will then
-resolve the variable for each event. Note that the pattern
-"%X\{loginId}" would achieve the same result.
+StrSubstitutor --> Interpolator
+
+class Interpolator {
+ StrLookup[] lookups
+ String lookup(String key)
+ String lookup(LogEvent event, String key)
+}
+
+Interpolator --> "0..*" StrLookup
+
+class StrLookup {
+ String lookup(String input)
+ String lookup(LogEvent event, String key)
+}
+
+@enduml
+....
+
+The property substitution system is composed of these elements:
+
+* A string interpolation engine
(xref:manual/architecture.adoc#StrSubstitutor[`StrSubstitutor`]) that evaluates
`$+{...}+` expressions.
+These expressions can contain recursive expressions and default values.
++
+See xref:manual/configuration.adoc#property-substitution[property
substitution] for more details.
+
+* The
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/Interpolator.html[`Interpolator`]
+that evaluates simple `$\{name}` expressions.
++
+The Interpolator has two functions:
+
+** If `name` does not contain a colon `:` character, the Interpolator uses the
+xref:manual/configuration.adoc#global-properties[`Properties` configuration
element] to resolve its value.
+
+** If `name` is of the form `prefix:key`, the Interpolator delegates the
lookup to a `StrLookup` associated with `prefix` and falls back to evaluating
`$+{key}+` if the lookup was not successful.
+
+* A set of
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-StrLookup[`StrLookup`]
+plugins, each one associated with a prefix, which retrieve data from external
sources.
+
+`StrLookup` is a simple map-like interface.
+The main difference between a map and `StrLookup` is that the latter can
compute the value of a key programmatically in a global context or in the
context of log event.
+
+[#common-concerns]
+== Common concerns
+
+[#evaluation-contexts]
+=== Evaluation contexts
+
+Each lookup has an associated prefix, and Log4j can evaluate it in one of the
following ways:
+
+[#global-context]
+Global context::
+In a global context Log4j evaluates `$+{prefix:key}+` expressions by calling
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html#lookup(java.lang.String)[`lookup("key")`]
+on the lookup associated to `prefix`.
+The result of this call only takes into account the global state of the system.
++
+The global context is used to expand the attributes of a
+xref:manual/configuration.adoc[configuration file].
+
+[#event-context]
+Log event context::
+In the context of a log event `event`, Log4j evaluates `$+{prefix:key}+`
expressions by calling
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html#lookup(org.apache.logging.log4j.core.LogEvent,java.lang.String)[`lookup(event,
"key")`] on the lookup associated to `prefix`.
+The result of this call might take into account the contents of the log event,
besides the global state of the system.
+
+Some configuration attributes (e.g.,
xref:manual/pattern-layout.adoc#plugin-attr-pattern[the `pattern` attribute of
Pattern Layout]) supports both evaluation contexts:
+
+* During the configuration process the `$+{...}+` expressions are evaluated
using a global context.
+The same process converts escaped `$$+{...}+` expressions to `$+{...}+`
expressions.
+
+* For each log event, the remaining expressions are evaluated, using the log
event as context.
+
+Lookups can choose to react differently depending on the execution context.
+<<DateLookup>> is such an example:
+
+* When used in a global context, it formats the **current** timestamp obtained
through
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/System.html#currentTimeMillis--[`System.currentTimeMillis()`].
+* When used in the context of an event, it formats the **event** timestamp
obtained through
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html#getTimeMillis()[`LogEvent.getTimeMillis()`].
+
+[#lookups-patterns]
+=== Lazy lookups and pattern converters
+
+For historical reasons, the
+xref:manual/pattern-layout.adoc#plugin-attr-pattern[`pattern` attribute of
PatternLayout]
+supports two similar string replacement mechanisms:
+
+* `+${...}+` property expressions.
+* xref:manual/pattern-layout.adoc#converters[`%<name>` pattern converters].
+
+Both lazy `+$${...}+` property expressions and pattern converters have access
to the value of the current `LogEvent` and can provide similar results.
+There is, however, an important difference between them:
Review Comment:
I don't really have an opinion on which one users should use.
Pattern converters are more performant, but if users want to use runtime
lookups, I don't see a big problem in that.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
