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 <[email protected]>
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
