This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new 52ca6a352c Fix `UuidPatternConverter` docs (#3768)
52ca6a352c is described below
commit 52ca6a352c655de1002f66aaf7809ebd049d7f7a
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
