ppkarwasz commented on code in PR #2736: URL: https://github.com/apache/logging-log4j2/pull/2736#discussion_r1677616123
########## 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: + +* A large group of lookups is available in a global context and provides results, which do not vary in time. +These lookups can be safely used in eagerly evaluated properties of a +xref:manual/configuration.adoc[configuration file] +using the `${prefix:key}` syntax: ++ +[#global-context-immutable-list] +.Immutable lookups available in the global context +[cols="1,2m,5"] +|=== +| Prefix | Dependency | Data source -[#ContextMapLookup] -== Context Map Lookup +| <<ResourceBundleLookup,`bundle`>> +| +| A Java +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/ResourceBundle.html[resource bundle] -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. +| <<DockerLookup,`docker`>> +| log4j-docker +| Docker container + +| <<EnvironmentLookup,`env`>> +| +| Environment variables + +| <<JavaLookup,`java`>> +| +| JVM characteristics + +| <<Log4jLookup,`log4j`>> +| +| Location of Log4j configuration file + +| <<MainMapLookup,`main`>> +| +| JVM application arguments + +| <<MarkerLookup,`marker`>> +| +| Returns `key` if a marker named `key` exists + +| <<SpringBootLookup,`spring`>> +| log4j-spring-boot +| Spring Boot 2.x environment. + +| <<SystemPropertiesLookup,`sys`>> +| +| Java system properties + +| <<WebLookup,`web`>> +| log4j-jakarta-web +| Jakarta +https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servletcontext[`ServletContext`]. + +|=== + +* A second group of lookups either gives results that vary in time or needs to be evaluated in the context of a log event. +These lookups should be evaluated lazily using the `$$+{prefix:key}+` syntax. +See +xref:manual/configuration.adoc#lazy-property-substitution[lazy property substitution] +for details. ++ +[#global-context-mutable-list] +.Mutable lookups available in the global context +[cols="1,2m,5"] +|=== +| Prefix | Dependency | Data source + +| <<ContextMapLookup,`ctx`>> +| +| xref:manual/thread-context.adoc[] + +| <<DateLookup,`date`>> +| +| Current timestamp + +| <<JndiLookup,`jndi`>> +| +| JNDI + +|=== ++ +[#event-context-list] +.Lookups available in the context of a log event +[cols="1,2m,5"] +|=== +| Prefix | Dependency | Data source + +| <<ContextMapLookup,`ctx`>> +| +| Log event +link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html#getContextData()[context data] + +| <<DateLookup,`date`>> +| +| Log event +link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html#getTimeMillis()[timestamp] + +| <<EventLookup,`event`>> +| +| link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[Log event] + +| <<MapLookup,`map`>> +| +| xref:manual/messages.adoc#MapMessage[`MapMessage`] + +| <<MarkerLookup,`marker`>> +| +| Log event +link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html#getMarker()[marker] + +| <<StructuredDataLookup,`sd`>> +| +| xref:manual/messages.adoc#StructuredDataMessage[`StructuredDataMessage`] + +|=== + +* Log4j Core also provides two lookups that can be used to modify the result of another lookup: ++ +[#helper-lookups-list] +.Helper lookups +[cols="1,2m,5"] +|=== +| Prefix | Dependency | Description + +| <<LowerLookup,`lower`>> +| +| It converts the supplied key to lowercase + +| <<UpperLookup,`upper`>> +| +| It converts the supplied key to uppercase + +|=== + +[#ResourceBundleLookup] +=== Resource Bundle Lookup + +[cols="1h,4"] +|=== +| Lookup ID | `bundle` + +| Context | _global_ + +| Key format +a| `<baseName> ":" <key>` + +where: + +`baseName`:: +the base name of a resource bundle (see +https://docs.oracle.com/javase/8/docs/api/java/util/ResourceBundle.html[`ResourceBundle`]) + +`key`:: +the key for the resource string +|=== + +The Resource Bundle lookup retrieves strings from Java Resource bundles, e.g.: -[source,xml] ---- -<File name="Application" fileName="application.log"> - <PatternLayout> - <pattern>%d %p %c{1.} [%t] $${ctx:loginId} %m%n</pattern> - </PatternLayout> -</File> +${bundle:org.example.Main:errorMessage} ---- +[#ContextMapLookup] +=== Context Map Lookup + +[cols="1h,4"] +|=== +| Lookup ID | `ctx` +| Context | _global_ and _log event_ +| Key format | _any_ `String` +|=== + +The Context Map lookup can be used in two different contexts: + +Global context:: +If used in the global context, it uses the +xref:manual/thread-context.adoc[] +to retrieve data. ++ +[WARNING] +==== +When used in this context +xref:manual/thread-context.adoc#custom-ContextDataProvider[custom context data providers] +are not supported. +==== + +Log event context:: +In the context of an event, the Context Map lookup uses the +Log event +link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html#getContextData()[context map data] +of a log event to resolve the key. +xref:manual/thread-context.adoc#custom-ContextDataProvider[Custom context data providers] are therefore supported. ++ +[TIP] +==== +Whenever conversion patterns are allowed, a `$$+{ctx:key}+` lookup is equivalent to an +xref:manual/pattern-layout.adoc#converter-thread-context-map[`%X\{key}` pattern]. +==== + [#DateLookup] -== Date Lookup +=== Date Lookup -The DateLookup is somewhat unusual from the other lookups as it doesn't -use the key to locate an item. Instead, the key can be used to specify a -date format string that is valid for -https://docs.oracle.com/javase/{java-target-version}/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`]. -The current date, or the date associated with the current log event will -be formatted as specified. +[cols="1h,4"] +|=== +| Lookup ID | `date` -[source,xml] ----- -<RollingFile name="Rolling-${map:type}" fileName="${filename}" filePattern="target/rolling1/test1-$${date:MM-dd-yyyy}.%i.log.gz"> - <PatternLayout> - <pattern>%d %p %c{1.} [%t] %m%n</pattern> - </PatternLayout> - <SizeBasedTriggeringPolicy size="500" /> -</RollingFile> ----- +| Context | _global_ and _log event_ + +| Key format Review Comment: Fixed in https://github.com/apache/logging-log4j2/pull/2736/commits/b63461d178d2f33b84bf8854bbdf578d5c27dad7 -- 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]
