Skip to content

Commit

Permalink
[WFLY-18490] Update the logging for the Common Enhancements. Refactor…
Browse files Browse the repository at this point in the history
… the quickstart to use a more modern approach.

Signed-off-by: James R. Perkins <[email protected]>
  • Loading branch information
jamezp committed Nov 22, 2023
1 parent 59d4d80 commit 93a4e89
Show file tree
Hide file tree
Showing 13 changed files with 833 additions and 338 deletions.
17 changes: 17 additions & 0 deletions .github/workflows/quickstart_logging_ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
name: WildFly logging Quickstart CI

on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
branches-ignore:
- 'dependabot/**'
paths:
- 'logging/**'
- '.github/workflows/quickstart_ci.yml'

jobs:
call-quickstart_ci:
uses: ./.github/workflows/quickstart_ci.yml
with:
QUICKSTART_PATH: logging
TEST_PROVISIONED_SERVER: true
162 changes: 38 additions & 124 deletions logging/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,19 @@ include::../shared-doc/attributes.adoc[]
:technologies: Logging

[abstract]
The `logging` quickstart demonstrates how to configure different logging levels in {productName}. It also includes an asynchronous logging example.
The `logging` quickstart demonstrates how to configure different logging levels in {productName}.

:standalone-server-type: default
:archiveType: war
:restoreScriptName: remove-logging.cli

== What is it?

The `logging` quickstart demonstrates how to set up and log different levels of information in {productNameFull}. An example of asynchronous logging is also included in the configuration examples.
The `logging` quickstart demonstrates how to set up and log different levels of information in {productNameFull}.

This quickstart contains just one class file and one JSP file. When you access the application, it fires off the logging information.
This quickstart contains contains a simple REST endpoint which will log messages. The `index.html` page can be used
to log messages and see the results. However, you could use a REST client or something like `cURL` to invoke log
messages.

To better visualize how the logging configuration works, you first deploy and access the application before configuring the logs and view the resulting log files. Then you configure the logs, redeploy and access the application, and look at the log files again to see the differences.

Expand All @@ -30,6 +32,11 @@ include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]
// Build and Deploy the Quickstart
include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]
// Build and run sections for other environments/builds
ifndef::ProductRelease,EAPXPRelease[]
include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1]
endif::[]
include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1]

[[access_the_application]]
== Access the Application
Expand All @@ -40,22 +47,19 @@ You will see the following message in the server console:

[source,options="nowrap"]
----
FATAL [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS A FATAL MESSAGE
ERROR [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS AN ERROR MESSAGE
WARN [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS A WARNING MESSAGE
INFO [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS AN INFO MESSAGE
ERROR [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS AN ERROR MESSAGE
FATAL [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS A FATAL MESSAGE
INFO [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS AN INFO MESSAGE
WARN [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS A WARNING MESSAGE
18:20:33,272 FATAL [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an FATAL message from 127.0.0.1:50130
18:20:34,530 ERROR [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an ERROR message from 127.0.0.1:50130
18:20:35,332 WARN [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an WARN message from 127.0.0.1:50130
18:20:36,254 INFO [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an INFO message from 127.0.0.1:50130
18:20:37,156 DEBUG [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an DEBUG message from 127.0.0.1:50130
18:20:38,003 TRACE [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an TRACE message from 127.0.0.1:50130
----

== Check the Server Logs

The log files are located in the `__{jbossHomeName}__/standalone/log` log directory. At this point you should see the following log files.

* `server.log` - This is the standard log produced by the application server. By default, it contains all the server log messages, including the server startup messages.
* `gc.log.0.current` - This garbage collection log is produced only if garbage collection is enabled on the server. It contains garbage collection activity that can be used for diagnostic purposes. This log can be ignored as it is not used in this quickstart.


== Configure the Server
Expand All @@ -68,7 +72,7 @@ Now you have deployed the quickstart with the default configuration, you run a m
* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above.


. Review the `configure-logging.cli` file in the root of this quickstart directory. This script configures the logging subsytem in the server configuration file. It configures the periodic rotating file handlers and the async handlers, creates the logger for our quickstart class and sets the level to TRACE, and assigns the async handlers for our quickstart class.
. Review the `configure-logging.cli` file in the root of this quickstart directory. This script configures the logging subsystem in the server configuration file. It configures the file handlers, creates the logger for our quickstart and sets the level to TRACE. It also assigns the handlers for our quickstart to our logger.
. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}__` with the path to your server:
+
[source,subs="+quotes,attributes+",options="nowrap"]
Expand All @@ -86,101 +90,6 @@ You should see the following result when you run the script:
The batch executed successfully
----

== Review the Modified Server Configuration

After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes.

The following XML was added to the `logging` subsystem.

[source,xml,options="nowrap"]
----
<async-handler name="TRACE_QS_ASYNC">
<level name="TRACE"/>
<queue-length value="1024"/>
<overflow-action value="block"/>
<subhandlers>
<handler name="FILE_QS_TRACE"/>
</subhandlers>
</async-handler>
<async-handler name="DEBUG_QS_ASYNC">
<level name="DEBUG"/>
<queue-length value="1024"/>
<overflow-action value="block"/>
<subhandlers>
<handler name="FILE_QS_DEBUG"/>
</subhandlers>
</async-handler>
<async-handler name="INFO_QS_ASYNC">
<level name="INFO"/>
<queue-length value="1024"/>
<overflow-action value="block"/>
<subhandlers>
<handler name="FILE_QS_INFO"/>
</subhandlers>
</async-handler>
<async-handler name="WARN_QS_ASYNC">
<level name="WARN"/>
<queue-length value="1024"/>
<overflow-action value="block"/>
<subhandlers>
<handler name="FILE_QS_WARN"/>
</subhandlers>
</async-handler>
<async-handler name="ERROR_QS_ASYNC">
<level name="ERROR"/>
<queue-length value="1024"/>
<overflow-action value="block"/>
<subhandlers>
<handler name="FILE_QS_ERROR"/>
</subhandlers>
</async-handler>
<async-handler name="FATAL_QS_ASYNC">
<level name="FATAL"/>
<queue-length value="1024"/>
<overflow-action value="block"/>
<subhandlers>
<handler name="FILE_QS_FATAL"/>
</subhandlers>
</async-handler>
...
<periodic-rotating-file-handler name="FILE_QS_TRACE">
<file relative-to="jboss.server.log.dir" path="quickstart.trace.log"/>
<suffix value=".yyyy.MM.dd"/>
</periodic-rotating-file-handler>
<periodic-rotating-file-handler name="FILE_QS_DEBUG">
<file relative-to="jboss.server.log.dir" path="quickstart.debug.log"/>
<suffix value=".yyyy.MM.dd"/>
</periodic-rotating-file-handler>
<periodic-rotating-file-handler name="FILE_QS_INFO">
<file relative-to="jboss.server.log.dir" path="quickstart.info.log"/>
<suffix value=".yyyy.MM.dd"/>
</periodic-rotating-file-handler>
<periodic-rotating-file-handler name="FILE_QS_WARN">
<file relative-to="jboss.server.log.dir" path="quickstart.warn.log"/>
<suffix value=".yyyy.MM.dd"/>
</periodic-rotating-file-handler>
<periodic-rotating-file-handler name="FILE_QS_ERROR">
<file relative-to="jboss.server.log.dir" path="quickstart.error.log"/>
<suffix value=".yyyy.MM.dd"/>
</periodic-rotating-file-handler>
<periodic-rotating-file-handler name="FILE_QS_FATAL">
<file relative-to="jboss.server.log.dir" path="quickstart.fatal.log"/>
<suffix value=".yyyy.MM.dd"/>
</periodic-rotating-file-handler>
...
<logger category="org.jboss.as.quickstarts.logging">
<level name="TRACE"/>
<handlers>
<handler name="TRACE_QS_ASYNC"/>
<handler name="DEBUG_QS_ASYNC"/>
<handler name="INFO_QS_ASYNC"/>
<handler name="WARN_QS_ASYNC"/>
<handler name="ERROR_QS_ASYNC"/>
<handler name="FATAL_QS_ASYNC"/>
</handlers>
</logger>
----

== Test the New Logging Configuration

. Make sure you xref:start_the_eap_standalone_server[start the {productName} server with the standalone default profile] as described above.
Expand All @@ -198,26 +107,35 @@ The log files are located in the `__{jbossHomeName}__/standalone/log` log direct
** `quickstart.error.log`
** `quickstart.fatal.log`

The following are the rest endpoint paths. Note these can be accessed from the `index.html` by clicking the buttons

* `/api/logs/trace`
* `/api/logs/debug`
* `/api/logs/info`
* `/api/logs/warn`
* `/api/logs/error`
* `/api/logs/fatal`

The following describes what happens when you access this quickstart:

. The application class file fires off logs of the various types (INFO, DEBUG, TRACE, WARN, ERROR, FATAL). Each log message goes to a different file, as defined in the `standalone.xml` file. Also notice in the `standalone.xml` that the application package defines its own log level.
. The class file demonstrates the usage of _log guards_. _Log guards_ are a development best practice. Simply put, instead of just writing out logs, we wrap the log writes in a check for that log level being enabled. While this may seem like overhead, that boolean check is more efficient than relying on the underlying framework to do the check at write time.
. When you access one of the above endpoints, a simple message is logged.
. Finally, the class file logs various levels, each to its own file as configured in `standalone.xml`. Note that log levels are hierarchical. When set, all log levels above the specified level are logged as well.
. Common uses of the 6 log levels are outlined below. You should use the level that makes the most sense in your environment.
+
[source,options="nowrap"]
----
FATAL - Used to track critical system failures. When this log message is written, it is writing application error that has caused service to cease. This is the most narrow logging.
ERROR - Used to track application errors that may cause one request to fail (not a service ceasement).
WARN - This is setting is used in most production environments. At this level, all *WARN*, *ERROR*, and *FATAL* messages are written. Use this level message as a predictive measure for possible forthcoming issues.
INFO - Usually only used in a development environment. This provides any information - state transition, object values, etc
WARN - Used for warnings. At this level, all *WARN*, *ERROR*, and *FATAL* messages are written. Use this level message as a predictive measure for possible forthcoming issues.
INFO - This provides any information - state transition, object values, etc
DEBUG - Turned on in any environment when a problem is occuring. The information captured may be throughput, communication, object values, etc.
TRACE - Turned on in any environment where you are trying to follow an execution path, for optimization or debugging. This is the most broad logging level and all messages are written.
----

. To view log file differences for different logging levels, change the level for the "org.jboss.as.quickstarts.logging" logger
from TRACE to DEBUG, INFO, WARN, ERROR, or FATAL, then access the application.

// Server Distribution Testing
include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2]
// Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]
// Restore the {productName} Standalone Server Configuration
Expand All @@ -228,7 +146,13 @@ This script removes the log and file handlers from the `logging` subsystem in th

[source,options="nowrap"]
----
The batch executed successfully
{"outcome" => "success"}
{"outcome" => "success"}
{"outcome" => "success"}
{"outcome" => "success"}
{"outcome" => "success"}
{"outcome" => "success"}
{"outcome" => "success"}
----

// Restore the {productName} Standalone Server Configuration Manually
Expand All @@ -242,13 +166,3 @@ include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[levelof

// Debug the Application
include::../shared-doc/debug-the-application.adoc[leveloffset=+1]

//*************************************************
// Product Release content only
//*************************************************
ifdef::ProductRelease[]
// Quickstart not compatible with OpenShift
include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1]
endif::[]
29 changes: 9 additions & 20 deletions logging/configure-logging.cli
Original file line number Diff line number Diff line change
@@ -1,22 +1,11 @@
# Batch script to add and configure logging in the JBoss EAP server

# Start batching commands
batch

# Add the periodic rotating file handlers corresponding to those added to the logging properties file
/subsystem=logging/periodic-rotating-file-handler=FILE_QS_TRACE:add(level=TRACE, suffix=".yyyy.MM.dd", file={"path"=>"quickstart.trace.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/periodic-rotating-file-handler=FILE_QS_DEBUG:add(level=DEBUG, suffix=".yyyy.MM.dd", file={"path"=>"quickstart.debug.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/periodic-rotating-file-handler=FILE_QS_INFO:add(level=INFO, suffix=".yyyy.MM.dd", file={"path"=>"quickstart.info.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/periodic-rotating-file-handler=FILE_QS_WARN:add(level=WARN, suffix=".yyyy.MM.dd", file={"path"=>"quickstart.warn.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/periodic-rotating-file-handler=FILE_QS_ERROR:add(level=ERROR, suffix=".yyyy.MM.dd", file={"path"=>"quickstart.error.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/periodic-rotating-file-handler=FILE_QS_FATAL:add(level=FATAL, suffix=".yyyy.MM.dd", file={"path"=>"quickstart.fatal.log", "relative-to"=>"jboss.server.log.dir"})

# Configure the logging async handlers
/subsystem=logging/async-handler=async:add(queue-length=1024, overflow-action=BLOCK, subhandlers=["FILE_QS_TRACE","FILE_QS_DEBUG","FILE_QS_INFO","FILE_QS_WARN","FILE_QS_ERROR","FILE_QS_FATAL"])

# Create the logger for our quickstart class
/subsystem=logging/logger=org.jboss.as.quickstarts.logging:add(handlers=[async])

# Run the batch commands
run-batch
/subsystem=logging/file-handler=FILE_QS_TRACE:add(append=false, level=TRACE, named-formatter=PATTERN, file={"path"=>"quickstart-trace.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/file-handler=FILE_QS_DEBUG:add(append=false, level=DEBUG, named-formatter=PATTERN, file={"path"=>"quickstart-debug.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/file-handler=FILE_QS_INFO:add(append=false, level=INFO, named-formatter=PATTERN, file={"path"=>"quickstart-info.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/file-handler=FILE_QS_WARN:add(append=false, level=WARN, named-formatter=PATTERN, file={"path"=>"quickstart-warn.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/file-handler=FILE_QS_ERROR:add(append=false, level=ERROR, named-formatter=PATTERN, file={"path"=>"quickstart-error.log", "relative-to"=>"jboss.server.log.dir"})
/subsystem=logging/file-handler=FILE_QS_FATAL:add(append=false, level=FATAL, named-formatter=PATTERN, file={"path"=>"quickstart-fatal.log", "relative-to"=>"jboss.server.log.dir"})

# Create the logger for our quickstart class and assign the handlers
/subsystem=logging/logger=org.jboss.as.quickstarts.logging:add(handlers=[FILE_QS_TRACE,FILE_QS_DEBUG,FILE_QS_INFO,FILE_QS_WARN,FILE_QS_ERROR,FILE_QS_FATAL])

Loading

0 comments on commit 93a4e89

Please sign in to comment.