Deterministic UUID option for PatternLayout

log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java

@@ -29,40 +29,60 @@
 @Plugin("UuidPatternConverter")
 @ConverterKeys({"u", "uuid"})
 public final class UuidPatternConverter extends LogEventPatternConverter {
+    private enum UuidType {
+        TIME,
+        RANDOM,
+        HASH
+    }
 
-    private final boolean isRandom;
+    private final UuidType uuidType;
 
     /**
      * Private constructor.
      */
-    private UuidPatternConverter(final boolean isRandom) {
+    private UuidPatternConverter(final UuidType uuidType) {
         super("u", "uuid");
-        this.isRandom = isRandom;
+        this.uuidType = uuidType;
     }
 
     /**
-     * Obtains an instance of SequencePatternConverter.
+     * Obtains an instance of UuidPatternConverter.
      *
-     * @param options options, currently ignored, may be null.
-     * @return instance of SequencePatternConverter.
+     * @param options options
+     * @return instance of UuidPatternConverter.
      */
     public static UuidPatternConverter newInstance(final String[] options) {
         if (options.length == 0) {
-            return new UuidPatternConverter(false);
+            return new UuidPatternConverter(UuidType.TIME);
         }
 
-        if (options.length > 1 || (!options[0].equalsIgnoreCase("RANDOM") && !options[0].equalsIgnoreCase("Time"))) {
-            LOGGER.error("UUID Pattern Converter only accepts a single option with the value \"RANDOM\" or \"TIME\"");
+        if (options.length == 1) {
+            switch (options[0].toUpperCase()) {
+                case "TIME":
+                    return new UuidPatternConverter(UuidType.TIME);
+                case "RANDOM":
+                    return new UuidPatternConverter(UuidType.RANDOM);
+                case "HASH":
+                    return new UuidPatternConverter(UuidType.HASH);
+            }
         }
-        return new UuidPatternConverter(options[0].equalsIgnoreCase("RANDOM"));
+
+        LOGGER.error(
+                "UUID Pattern Converter only accepts a single option with the value \"TIME\" or \"RANDOM\" or \"HASH\"");
+        return new UuidPatternConverter(UuidType.TIME);
     }
 
     /**
      * {@inheritDoc}
      */
     @Override
     public void format(final LogEvent event, final StringBuilder toAppendTo) {
-        final UUID uuid = isRandom ? UUID.randomUUID() : UuidUtil.getTimeBasedUuid();
+        final UUID uuid =
+                switch (uuidType) {
+                    case TIME -> UuidUtil.getTimeBasedUuid();
+                    case RANDOM -> UUID.randomUUID();
+                    case HASH -> UuidUtil.getLogEventBasedUuid(event);
+                };
         toAppendTo.append(uuid.toString());
     }
 }

log4j-core/src/main/java/org/apache/logging/log4j/core/util/UuidUtil.java

@@ -21,6 +21,7 @@
 import java.util.Random;
 import java.util.UUID;
 import java.util.concurrent.atomic.AtomicInteger;
+import org.apache.logging.log4j.core.LogEvent;
 import org.apache.logging.log4j.core.impl.CoreProperties.UuidProperties;
 import org.apache.logging.log4j.kit.env.PropertyEnvironment;
 
@@ -50,6 +51,7 @@ public final class UuidUtil {
     private static final int HUNDRED_NANOS_PER_MILLI = 10000;
 
     private static final long LEAST = initialize(NetUtils.getMacAddress());
+    private static final long SALT = new SecureRandom().nextLong();
 
     /* This class cannot be instantiated */
     private UuidUtil() {}
@@ -140,4 +142,47 @@ public static UUID getTimeBasedUuid() {
         final long most = timeLow | timeMid | TYPE1 | timeHi;
         return new UUID(most, LEAST);
     }
+
+    /**
+     * Generates a Type 4 UUID based on the deterministic LogEvent hash.
+     * Meant for generating consistent, correlatable UUID values across multiple Appenders for the same LogEvent.
+     *
+     * @param logEvent
+     * @return universally unique identifiers (UUID)
+     */
+    public static UUID getLogEventBasedUuid(LogEvent logEvent) {
+        // TODO: better hashing algorithm - include other LogEvent fields?
+        long epochSecond = logEvent.getInstant().getEpochSecond();
+        // Enable 'log4j.configuration.usePreciseClock' system property otherwise will be truncated to millis
+        long nanoOfSecond = logEvent.getInstant().getNanoOfSecond();
+        // Thread IDs typically increment from 0 producing a narrow range
+        long threadId = logEvent.getThreadId();
+
+        // Increase entropy
+        long most = mix(epochSecond, nanoOfSecond, threadId);
+        long least = mix(threadId, ~nanoOfSecond, epochSecond);
+        // Set UUID v4 bits
+        most &= 0xFFFFFFFFFFFF0FFFL;
+        most |= 0x0000000000004000L;
+        least &= 0x3FFFFFFFFFFFFFFFL;
+        least |= 0x8000000000000000L;
+
+        return new UUID(most, least);
+    }
+
+    private static long mix(long v1, long v2, long v3) {
+        // XOR with large primes
+        long hash = v1 * 0x9E3779B97F4A7C15L;
+        hash ^= (v2 * 0xC6BC279692B5C323L);
+        hash ^= (v3 * 0x3243F6A8885A308DL);
+        // Scramble
+        hash ^= (hash >>> 33);
+        hash *= 0xff51afd7ed558ccdL;
+        hash ^= (hash >>> 33);
+        hash *= 0xc4ceb9fe1a85ec53L;
+        hash ^= (hash >>> 33);
+        // Add salt
+        hash ^= SALT;
+        return hash;
+    }
 }