This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch 2.25.x in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 1d5cb80939ec2c5d4e43783205ef61c8cfdd5b92 Author: julianladisch <[email protected]> AuthorDate: Sat Jun 28 08:52:26 2025 +0200 Fix `UuidPatternConverter` docs (#3768) --- .../log4j/core/pattern/UuidPatternConverter.java | 17 +++++++++++++---- .../modules/ROOT/pages/manual/pattern-layout.adoc | 10 +++++++--- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java index bd93dcfbfa..c1a4aebd42 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java @@ -22,7 +22,7 @@ import org.apache.logging.log4j.core.config.plugins.Plugin; import org.apache.logging.log4j.core.util.UuidUtil; /** - * Formats the event sequence number. + * Formats a UUID. */ @Plugin(name = "UuidPatternConverter", category = PatternConverter.CATEGORY) @ConverterKeys({"u", "uuid"}) @@ -39,10 +39,19 @@ public final class UuidPatternConverter extends LogEventPatternConverter { } /** - * Obtains an instance of SequencePatternConverter. + * Creates an instance of {@link UuidPatternConverter}. + * <p> + * The {@code RANDOM} option generates a Type 4 (pseudo-randomly generated) UUID. + * The UUID is generated using a cryptographically strong pseudo-random number generator. + * <p> + * The {@code TIME} option generates a Type 1 (date and time based) UUID using the local network interface's MAC address. + * To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated. + * See {@link UuidUtil#UUID_SEQUENCE} how to seed the UUID generation with an integer value. + * Because time-based UUIDs contain the MAC address and timestamp, they should be used with care. * - * @param options options, currently ignored, may be null. - * @return instance of SequencePatternConverter. + * @param options An array containing either {@code RANDOM} or {@code TIME}. + * If empty, {@code TIME} will be used. + * @return a new {@link UuidPatternConverter} instance */ public static UuidPatternConverter newInstance(final String[] options) { if (options.length == 0) { diff --git a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc index d3f713e794..b6b4aa788f 100644 --- a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc @@ -1339,15 +1339,19 @@ Includes either a random or a time-based UUID .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/UuidPatternConverter.html[`UuidPatternConverter`] specifier grammar [source,text] ---- -u{RANDOM|TIME} -uuid{RANDOM|TIME} +u[{RANDOM|TIME}] +uuid[{RANDOM|TIME}] ---- -The time-based UUID is a Type 1 UUID generated using the MAC address of each host +The random UUID is a type 4 UUID. The UUID is generated using a cryptographically strong pseudo-random number generator. + +The time-based UUID is a Type 1 (date and time based) UUID generated using the MAC address of each host. To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated. See also xref:manual/systemproperties.adoc#log4j2.uuidSequence[`log4j2.uuidSequence`]. Because time-based UUIDs contain the MAC address and timestamp, they should be used with care. +TIME is the default. + [#format-modifiers] === Format modifiers
