ppkarwasz commented on code in PR #2736: URL: https://github.com/apache/logging-log4j2/pull/2736#discussion_r1677548084
########## src/site/antora/modules/ROOT/pages/manual/lookups.adoc: ########## @@ -16,63 +16,298 @@ //// = 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 loosely based on the +https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/StringSubstitutor.html[Commons Text `StringSubstitutor`]. + +The property substitution system is composed of two kinds of elements: + +* A string interpolation engine (xref:manual/architecture.adoc#StrSubstitutor[`StrSubstitutor`]) that evaluates `$+{...}+` expressions. +See xref:manual/configuration.adoc#property-substitution[property substitution] for more details. +* A set of +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-StrLookup[`StrLookup`] +plugins that provide values for simple `$+{prefix:key}+` expressions. + +`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. + +[#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. + +The xref:manual/pattern-layout.adoc#plugin-attr-pattern[`pattern`] attribute of `PatternLayout` is an example of attribute that supports both evaluation contexts: + +* During the configuration process the `$+{...}+` expressions are evaluated using a global context. +* For each log event the `$$+{...}+` expressions are evaluated, using the log event as context. + +An example of lookup that can be used in both a global and event context is the `$+{date:...}+` lookup: + +* 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()`]. + +[#collection] +== Collection + +Log4j Core provides many lookups out-of-the-box, which can be categorized into three non-disjoint groups: Review Comment: Fixed in fd9f75ed4be43ac9ae53f176d816fca0e0ff1140 -- 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]
