tessl/maven-org-apache-logging-log4j--log4j-core
A versatile, industrial-grade, and reference implementation of the Log4j API with rich components for various logging use cases.
—
Pending
lookups.mddocs/
Lookups
Lookups provide variable substitution capabilities in Log4j configurations, allowing dynamic values to be inserted into configuration elements at runtime. The lookup system supports environment variables, system properties, context data, and custom lookup implementations.
Capabilities
Core Lookup Interface
Base interface for implementing custom lookup providers.
/**
* Core lookup interface for variable substitution
*/
public interface StrLookup {
/**
* Look up a variable by key
* @param key Variable key to look up
* @return Variable value or null if not found
*/
String lookup(String key);
/**
* Look up a variable with LogEvent context
* @param event LogEvent providing context for lookup
* @param key Variable key to look up
* @return Variable value or null if not found
*/
String lookup(LogEvent event, String key);
}System Properties Lookup
Looks up Java system properties using System.getProperty().
/**
* SystemPropertiesLookup for accessing Java system properties
*/
public class SystemPropertiesLookup implements StrLookup {
/**
* Look up system property by key
* @param key System property name
* @return System property value or null
*/
public String lookup(String key);
/**
* Look up system property with LogEvent context
* @param event LogEvent for context
* @param key System property name
* @return System property value or null
*/
public String lookup(LogEvent event, String key);
}Usage Examples:
Configuration usage:
<Configuration>
<Properties>
<Property name="logPath">${sys:user.home}/logs</Property>
<Property name="javaVersion">${sys:java.version}</Property>
</Properties>
<Appenders>
<File name="File" fileName="${logPath}/application.log">
<PatternLayout pattern="Java ${javaVersion} - %d %level %logger - %msg%n"/>
</File>
</Appenders>
</Configuration>Environment Variables Lookup
Looks up operating system environment variables.
/**
* EnvironmentLookup for accessing OS environment variables
*/
public class EnvironmentLookup implements StrLookup {
/**
* Look up environment variable by key
* @param key Environment variable name
* @return Environment variable value or null
*/
public String lookup(String key);
/**
* Look up environment variable with LogEvent context
* @param event LogEvent for context
* @param key Environment variable name
* @return Environment variable value or null
*/
public String lookup(LogEvent event, String key);
}Usage Examples:
Configuration usage:
<Configuration>
<Properties>
<Property name="appName">${env:APP_NAME}</Property>
<Property name="environment">${env:ENVIRONMENT}</Property>
<Property name="logLevel">${env:LOG_LEVEL:-INFO}</Property>
</Properties>
<Appenders>
<File name="File" fileName="logs/${appName}-${environment}.log"/>
</Appenders>
</Configuration>Context Map Lookup
Looks up values from the thread context map (MDC).
/**
* ContextMapLookup for accessing ThreadContext data
*/
public class ContextMapLookup implements StrLookup {
/**
* Look up context value by key
* @param key Context key
* @return Context value or null
*/
public String lookup(String key);
/**
* Look up context value with LogEvent context
* @param event LogEvent containing context data
* @param key Context key
* @return Context value or null
*/
public String lookup(LogEvent event, String key);
}Usage Examples:
// Set context data
ThreadContext.put("userId", "12345");
ThreadContext.put("requestId", "req-abc-123");
// Configuration can reference context valuesConfiguration usage:
<Configuration>
<Appenders>
<File name="UserFile" fileName="logs/user-${ctx:userId}.log">
<PatternLayout pattern="Request ${ctx:requestId} - %d %level %logger - %msg%n"/>
</File>
</Appenders>
</Configuration>Date Lookup
Provides current date and time formatting capabilities.
/**
* DateLookup for formatting current date/time
*/
public class DateLookup implements StrLookup {
/**
* Format current date/time using specified pattern
* @param key Date format pattern (SimpleDateFormat)
* @return Formatted date string
*/
public String lookup(String key);
/**
* Format current date/time with LogEvent timestamp
* @param event LogEvent for timestamp context
* @param key Date format pattern
* @return Formatted date string
*/
public String lookup(LogEvent event, String key);
}Usage Examples:
Configuration usage:
<Configuration>
<Properties>
<Property name="currentDate">${date:yyyy-MM-dd}</Property>
<Property name="timestamp">${date:yyyy-MM-dd_HH-mm-ss}</Property>
</Properties>
<Appenders>
<File name="DailyFile" fileName="logs/app-${currentDate}.log"/>
<File name="StartupFile" fileName="logs/startup-${timestamp}.log"/>
</Appenders>
</Configuration>Java Lookup
Provides access to Java runtime information.
/**
* JavaLookup for accessing Java runtime information
*/
public class JavaLookup implements StrLookup {
/**
* Look up Java runtime information
* @param key Information key (version, runtime, vm, os, locale, hw)
* @return Java runtime information
*/
public String lookup(String key);
}Usage Examples:
Configuration usage:
<Configuration>
<Properties>
<Property name="javaVersion">${java:version}</Property>
<Property name="javaRuntime">${java:runtime}</Property>
<Property name="javaVm">${java:vm}</Property>
<Property name="osInfo">${java:os}</Property>
<Property name="hwInfo">${java:hw}</Property>
</Properties>
</Configuration>Main Arguments Lookup
Provides access to main method arguments.
/**
* MainMapLookup for accessing main method arguments
*/
public class MainMapLookup implements StrLookup {
/**
* Look up main argument by index
* @param key Argument index as string
* @return Argument value or null
*/
public String lookup(String key);
}JNDI Lookup
Provides JNDI (Java Naming and Directory Interface) lookups.
/**
* JndiLookup for JNDI resource access
* NOTE: Disabled by default for security reasons in Log4j 2.17.0+
*/
public class JndiLookup implements StrLookup {
/**
* Look up JNDI resource
* @param key JNDI name
* @return JNDI resource or null
*/
public String lookup(String key);
}Security Note: JNDI lookup is disabled by default in Log4j 2.17.0+ due to security concerns. Enable only if absolutely necessary and in trusted environments.
Upper/Lower Case Lookups
Transforms lookup values to upper or lower case.
/**
* UpperLookup - converts nested lookup results to uppercase
*/
public class UpperLookup implements StrLookup {
public String lookup(String key);
}
/**
* LowerLookup - converts nested lookup results to lowercase
*/
public class LowerLookup implements StrLookup {
public String lookup(String key);
}Usage Examples:
Configuration usage:
<Configuration>
<Properties>
<Property name="upperEnv">${upper:${env:ENVIRONMENT}}</Property>
<Property name="lowerUser">${lower:${sys:user.name}}</Property>
</Properties>
</Configuration>Custom Lookup Implementation
Creating Custom Lookups
/**
* Example custom lookup plugin
*/
@Plugin(name = "database", category = StrLookup.CATEGORY)
public class DatabaseLookup implements StrLookup {
private final DataSource dataSource;
public DatabaseLookup(DataSource dataSource) {
this.dataSource = dataSource;
}
/**
* Look up value from database
* @param key Database key to query
* @return Database value or null
*/
@Override
public String lookup(String key) {
try (Connection conn = dataSource.getConnection();
PreparedStatement stmt = conn.prepareStatement("SELECT value FROM config WHERE key = ?")) {
stmt.setString(1, key);
try (ResultSet rs = stmt.executeQuery()) {
return rs.next() ? rs.getString("value") : null;
}
} catch (SQLException e) {
LOGGER.error("Database lookup failed for key: {}", key, e);
return null;
}
}
/**
* Factory method for creating lookup instances
* @return DatabaseLookup instance
*/
@PluginFactory
public static DatabaseLookup createLookup() {
// Initialize DataSource
return new DatabaseLookup(createDataSource());
}
}Lookup Syntax and Nesting
Basic Syntax
${lookup:key}- Simple lookup${lookup:key:-default}- Lookup with default value
Nested Lookups
<!-- Nested environment and system property lookups -->
<Property name="logFile">${env:${sys:app.name.property}}.log</Property>
<!-- Complex nesting with defaults -->
<Property name="dbUrl">${env:DATABASE_URL:-${sys:default.db.url:-jdbc:h2:mem:test}}</Property>Conditional Lookups
<!-- Use environment-specific configuration -->
<Property name="configFile">config-${env:ENVIRONMENT:-development}.xml</Property>Built-in Lookup Prefixes
Standard lookup prefixes available in Log4j Core:
${ctx:key}- Thread context map lookup${date:pattern}- Date formatting lookup${env:key}- Environment variables lookup${sys:key}- System properties lookup${java:key}- Java runtime information lookup${main:index}- Main method arguments lookup${upper:nested}- Uppercase transformation lookup${lower:nested}- Lowercase transformation lookup${jndi:name}- JNDI lookup (security restricted)
Install with Tessl CLI
npx tessl i tessl/maven-org-apache-logging-log4j--log4j-core