From 115b2df74520f356f22df6c5d12a053c742082bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Mat=C4=9Bj=C4=8Dek?= <david.matejcek@omnifish.ee>
Date: Sat, 11 May 2024 21:17:46 +0200
Subject: [PATCH] Fixed javadocs and added documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: David Matějček <david.matejcek@omnifish.ee>
---
 .../src/main/asciidoc/logging.adoc               | 16 ++++++++++++++++
 .../cfg/GlassFishLogManagerConfiguration.java    | 11 ++++++-----
 .../main/jul/cfg/GlassFishLoggingConstants.java  |  9 +++++----
 3 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/docs/administration-guide/src/main/asciidoc/logging.adoc b/docs/administration-guide/src/main/asciidoc/logging.adoc
index db14d6728a8..673f21cc747 100644
--- a/docs/administration-guide/src/main/asciidoc/logging.adoc
+++ b/docs/administration-guide/src/main/asciidoc/logging.adoc
@@ -271,6 +271,22 @@ If you edit `logging.properties` manually on an instance managed by the node, it
 overwritten on the next synchronization with DAS.
 ====
 
+[[log-records]]
+
+=== Log Records
+
+Because the automatic detection of caller class and method from stacktrace significantly affects
+performance of the logging system, we added the `org.glassfish.main.jul.classAndMethodDetection.enabled`
+property which affects the `*.printSource` property of formatters.
+
+* If this key is set to true, GJULE will detect the caller class and method from stacktrace,
+which is quite expensive operation affecting logging throughput.
+* If it is set to false, GJULE will not perform such detection. Formatters which use `getSourceClassName`
+or `getSourceMethodName` of the record will receive `null` unless the log record has set these values explicitly.
+* If the property is not set, GJULE makes the decision based on the (`*.printSource` property) - if
+any formatter requires this feature, the feature is enabled. Note that the `*.printSource` property
+must be explicitly set to true in `logging.properties`.
+* It is disabled otherwise.
 
 [[loggers]]
 
diff --git a/nucleus/glassfish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLogManagerConfiguration.java b/nucleus/glassfish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLogManagerConfiguration.java
index 463e2c58c9a..b23e1cfb1b8 100644
--- a/nucleus/glassfish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLogManagerConfiguration.java
+++ b/nucleus/glassfish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLogManagerConfiguration.java
@@ -100,13 +100,14 @@ public boolean isTracingEnabled() {
      * GJULE will detect the caller class and method from stacktrace,
      * which is quite expensive operation affecting logging throughput.
      * <p>
-     * If it is set to null, GJULE will not perform such detection.
+     * If it is set to false, GJULE will not perform such detection.
      * <p>
-     * If the property is not set, GJULE makes the decision based on known handlers
-     * (<code>*.printSource</code> value) - if any handler requires this feature, it is enabled.
-     * It is disabled otherwise or you can forcibly enable it by setting the value to true or false.
+     * If the property is not set, GJULE makes the decision based on the(<code>*.printSource</code>
+     * property) - if any formatter requires this feature, the feature is enabled.
+     * <p>
+     * It is disabled otherwise.
      *
-     * @return true if handlers can use source class and method in formatters.
+     * @return true if formatters can use autodetected source class and method in formatters.
      */
     public boolean isClassAndMethodDetectionEnabled() {
         return classAndMethodDetectionEnabled;
diff --git a/nucleus/glassfish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLoggingConstants.java b/nucleus/glassfish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLoggingConstants.java
index d24c32fda5e..2e17a4cc72a 100644
--- a/nucleus/glassfish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLoggingConstants.java
+++ b/nucleus/glassfish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLoggingConstants.java
@@ -72,11 +72,12 @@ public class GlassFishLoggingConstants {
      * If this key is set to true, GJULE will detect the caller class and method from stacktrace,
      * which is quite expensive operation affecting logging throughput.
      * <p>
-     * If it is set to null, GJULE will not perform such detection.
+     * If it is set to false, GJULE will not perform such detection.
      * <p>
-     * If the property is not set, GJULE makes the decision based on known handlers
-     * (<code>*.printSource</code> value) - if any handler requires this feature, it is enabled.
-     * It is disabled otherwise or you can forcibly enable it by setting the value to true or false.
+     * If the property is not set, GJULE makes the decision based on the (<code>*.printSource</code>
+     * property) - if any formatter requires this feature, the feature is enabled.
+     * <p>
+     * It is disabled otherwise.
      */
     public static final String KEY_CLASS_AND_METHOD_DETECTION_ENABLED = "org.glassfish.main.jul.classAndMethodDetection.enabled";
     /**