(brooklyn-docs) branch master updated: Document returnStackTraces option and logging categories incl new LoginLogging

[he...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

heneveld pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git


The following commit(s) were added to refs/heads/master by this push:
     new c30caf88 Document returnStackTraces option and logging categories incl new LoginLogging
c30caf88 is described below

commit c30caf88a145856b3f87e2e78bfef374d4c9afa8
Author: Alex Heneveld <gi...@alex.heneveld.org>
AuthorDate: Tue Jan 21 13:09:55 2025 +0000

    Document returnStackTraces option and logging categories incl new LoginLogging
---
 guide/dev/tips/logging.md               |  2 +-
 guide/ops/configuration/brooklyn_cfg.md | 10 +++++++++-
 guide/ops/logging/index.md              | 24 +++++++++++++++++-------
 3 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/guide/dev/tips/logging.md b/guide/dev/tips/logging.md
index 9d66db21..7204a92b 100644
--- a/guide/dev/tips/logging.md
+++ b/guide/dev/tips/logging.md
@@ -3,7 +3,7 @@ title: Logging
 layout: website-normal
 ---
 
-## Logging: A Quick Overview
+## Logging for Developers: A Quick Overview
 
 For logging, we use **log4j** which implements the slf4j API.
 This means you can use any slf4j compliant logging framework,
diff --git a/guide/ops/configuration/brooklyn_cfg.md b/guide/ops/configuration/brooklyn_cfg.md
index 30a799ba..5d16a31d 100644
--- a/guide/ops/configuration/brooklyn_cfg.md
+++ b/guide/ops/configuration/brooklyn_cfg.md
@@ -259,7 +259,15 @@ seconds as properties on `brooklyn.cfg`:
 org.apache.brooklyn.server.maxSessionAge = 3600
 org.apache.brooklyn.server.maxInactiveInterval = 3600
 {% endhighlight %}
-  
+
+A further property `org.apache.brooklyn.server.returnStackTraces` can be set
+to control whether REST requests that have errors include stack traces:
+`true` or `all` to do this always; 
+`false` or `none` means never; 
+and `root` or `power` does so only for users with root or powerUser entitlements, respectively. 
+A unique reference identifier is returned and included in the logs for correlation.
+
+
 ## Login Page
 
 When using a username/password based authentication mechanism, Apache Brooklyn will be default respond with a 401
diff --git a/guide/ops/logging/index.md b/guide/ops/logging/index.md
index f7b4bb7b..b22007f8 100644
--- a/guide/ops/logging/index.md
+++ b/guide/ops/logging/index.md
@@ -7,6 +7,23 @@ check_directory_for_children: true
 Brooklyn uses the SLF4J logging facade, which allows use of many popular frameworks including `logback`,
 `java.util.logging` and `log4j`.
 
+Most loggers follow the ``package.ClassName`` naming standard,
+apart from some high-level ones which simplify the package and classname.
+
+For handy reference, the most commonly used logging categories are:
+
+* `org.apache.brooklyn.rest.security.LoginLogging`: login and logouts
+* `org.apache.brooklyn.REST`: REST handling details
+* `org.apache.brooklyn.SSH`: SSH i/o details
+* `org.apache.brooklyn.WinRm`: WinRM i/o details
+* `org.apache.brooklyn.core.mgmt.internal.BrooklynGarbageCollector`: Java memory GC details
+
+The default logging is to write INFO+ messages to `brooklyn.info.log`,
+and DEBUG+ to `brooklyn.debug.log`. Each is a rolling log file,
+where the past 10 files will be kept. INFO level, and above, messages
+will be logged to the karaf console. Use the `log:` commands in the
+karaf client, e.g. `log:tail`, to read these messages.
+
 The convention for log levels is as follows:
 
 * `ERROR` and above:  exceptional situations which indicate that something has unexpectedly failed or
@@ -16,13 +33,6 @@ The convention for log levels is as follows:
 * `DEBUG`:  detail of activity which might merit closer inspection under certain circumstances.
 * `TRACE` and lower: detail of activity which is not normally of interest, but which might merit closer inspection under certain circumstances including sensitive information (e.g. secrets) that should not be exposed in higher lover levels. A configuration example for TRACE level is present in the log configuration file, but is commented because of security concerns.
 
-Loggers follow the ``package.ClassName`` naming standard.
-
-The default logging is to write INFO+ messages to `brooklyn.info.log`,
-and DEBUG+ to `brooklyn.debug.log`. Each is a rolling log file,
-where the past 10 files will be kept. INFO level, and above, messages
-will be logged to the karaf console. Use the `log:` commands in the
-karaf client, e.g. `log:tail`, to read these messages.
 
 
 ## Using Logback through OSGi Pax Logging