From 528ac643ac49205ef6f2d6235a84e578a7fb9063 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Mon, 3 Jan 2022 10:47:43 +0100 Subject: [PATCH] =?UTF-8?q?Issue=20#7299=20-=20Enabling=20the=20logging-lo?= =?UTF-8?q?gback=20module=20prevents=20eclipse=20re=E2=80=A6=20(#7335)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Issue #7299 - Enabling the logging-logback module prevents eclipse remote debugging. Added documentation as discussed in the issue. Signed-off-by: Simone Bordet --- .../logging/logging-server.adoc | 14 ++-- .../start/start-configure.adoc | 25 ++++++- .../troubleshooting/chapter.adoc | 1 + .../troubleshooting/remote-debug.mod | 5 ++ .../troubleshooting-debugging.adoc | 74 +++++++++++++++++++ .../programming-guide/troubleshooting.adoc | 4 +- 6 files changed, 112 insertions(+), 11 deletions(-) create mode 100644 documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod create mode 100644 documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/troubleshooting-debugging.adoc diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/logging/logging-server.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/logging/logging-server.adoc index 3c74184275d..8fc8b31a0de 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/logging/logging-server.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/logging/logging-server.adoc @@ -58,8 +58,6 @@ Specifies the timezone ID (such as `PST`, or `America/Los_Angeles` or `GMT-8:00` The empty string specifies the `UTC` timezone. Default value is the local timezone. -// TODO: add a xref to the console-capture module. - The `logging-jetty` Jetty module, enabled transitively, provides the configuration file `$JETTY_BASE/resources/jetty-logging.properties` to configure the logging levels, for example: ---- @@ -107,7 +105,7 @@ See the xref:og-module-console-capture[`console-capture` module] for more inform [NOTE] ==== -The `console-capture` Jetty module should be used only in conjunction with the `logging-jetty` module, as other SLF4J bindings such as LogBack or Log4J2 have their own, more sophisticated, rolling file appenders. +The `console-capture` Jetty module should be used only in conjunction with the `logging-jetty` module, as other SLF4J bindings such as LogBack or Log4j2 have their own, more sophisticated, rolling file appenders. ==== [[og-logging-server-custom]] @@ -117,8 +115,8 @@ You can use a different SLF4J binding if you are more familiar with other loggin There are a number of out-of-the-box Jetty modules that you can use: * `logging-logback`, to use the link:http://logback.qos.ch/[LogBack] binding -* `logging-log4j2`, to use the link:https://logging.apache.org/log4j/2.x/[Log4J2] binding -* `logging-log4j1`, to use the link:https://logging.apache.org/log4j/1.2/[Log4J1] binding (note that Log4J 1.x is end-of-life) +* `logging-log4j2`, to use the link:https://logging.apache.org/log4j/2.x/[Log4j2] binding +* `logging-log4j1`, to use the link:https://logging.apache.org/log4j/1.2/[Log4j1] binding (note that Log4j 1.x is end-of-life) * `logging-jul`, to use the `java.util.logging` binding * `logging-noop`, to use the SLF4J no-operation binding (discards all logging) @@ -151,7 +149,7 @@ As you can see, the Jetty module system downloaded the required LogBack `+*.jar+ Please refer to the link:http://logback.qos.ch/manual/configuration.html[LogBack configuration manual] for more information about how to configure LogBack. [[og-logging-server-custom-log4j2]] -====== Logging with Log4J2 +====== Logging with Log4j2 Similarly to xref:og-logging-server-custom-logback[logging with LogBack], you can enable the `logging-log4j2` Jetty module in this way (from the `$JETTY_BASE` directory): @@ -159,7 +157,7 @@ Similarly to xref:og-logging-server-custom-logback[logging with LogBack], you ca $ java -jar $JETTY_HOME/start.jar --add-modules=logging-log4j2,http ---- -After accepting the Log4J2 license, you will have the following directory structure: +After accepting the Log4j2 license, you will have the following directory structure: ---- $JETTY_BASE @@ -175,7 +173,7 @@ $JETTY_BASE └── logging-log4j2.ini ---- -The Jetty module system downloaded the required Log4J2 `+*.jar+` files, and created a `$JETTY_BASE/resources/log4j2.xml` file that you can configure to customize your Log4J2 logging. +The Jetty module system downloaded the required Log4j2 `+*.jar+` files, and created a `$JETTY_BASE/resources/log4j2.xml` file that you can configure to customize your Log4j2 logging. [[og-logging-server-bridges]] ===== Bridging Logging to SLF4J diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc index e711d9018ea..39931adfaf1 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc @@ -24,7 +24,7 @@ Within the Jetty start mechanism, the source of configurations is layered in thi [[og-start-configure-enable]] ===== Enabling Modules -You can enable Jetty modules with the `--add-modules` command: +You can enable Jetty modules persistently across restarts with the `--add-modules` command: ---- $ java -jar $JETTY_HOME/start.jar --add-modules=server,http @@ -108,6 +108,29 @@ jetty.http.port=9876 When Jetty is started (or re-started) this configuration is applied and Jetty will listen for clear-text HTTP/1.1 on port `9876`. +[[og-start-configure-enable-command-line]] +===== Enabling Modules on Command Line + +You can also enable a module transiently, only for the current execution of the `java -jar $JETTY_HOME/start.jar` command. + +If you have an empty `$JETTY_BASE`, the following command enables the `server` and `http` modules, but does not create any `+$JETTY_BASE/start.d/*.ini+` files. + +---- +$ java -jar $JETTY_HOME/start.jar --module=server,http +---- + +Since there are no `+$JETTY_BASE/start.d/*.ini+` files, you can only customize the properties via the command line, for example: + +---- +$ java -jar $JETTY_HOME/start.jar --module=server,http jetty.http.port=9876 +---- + +Enabling modules on the command line is useful to verify that the modules work as expected, or to try different configurations. + +NOTE: It is possible to enable some module persistently via `--add-modules` and some other module transiently via `--module`. + +Remember that once the current execution terminates, the modules enabled transiently on the command line via `--module` and their configuration are not saved and will not be enabled on the next execution (unless you specify them again on the command line). + [[og-start-configure-custom-module]] ===== Adding Your Own Modules diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/chapter.adoc index d46a4a94eb9..59124b3dbbe 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/chapter.adoc @@ -35,3 +35,4 @@ IMPORTANT: Make sure you read about how to secure the access to Jetty when using include::troubleshooting-dump.adoc[] include::troubleshooting-logging.adoc[] +include::troubleshooting-debugging.adoc[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod new file mode 100644 index 00000000000..9cae360e33f --- /dev/null +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod @@ -0,0 +1,5 @@ +[description] +Enables remote debugging + +[exec] +-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/troubleshooting-debugging.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/troubleshooting-debugging.adoc new file mode 100644 index 00000000000..5257adb8a6f --- /dev/null +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/troubleshooting-debugging.adoc @@ -0,0 +1,74 @@ +// +// ======================================================================== +// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under the +// terms of the Eclipse Public License v. 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 +// which is available at https://www.apache.org/licenses/LICENSE-2.0. +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[og-troubleshooting-debugging]] +==== Remote Debugging + +The Java Virtual Machines allows remote processes on different hosts to connect for debugging purposes, by using specific command line options. + +[CAUTION] +==== +While it is possible to enable remote debugging on a Jetty server, it is typically not recommended for security and performance reasons. +Only enable remote debugging on a Jetty server as a last resort to troubleshoot issues that could not be troubleshot otherwise. +==== + +You can easily create a custom Jetty module (see xref:og-modules-custom[this section]) with the following content: + +.remote-debug.mod +---- +include::remote-debug.mod[] +---- + +The `[exec]` directive (documented xref:og-modules-directive-exec[here]) is necessary to pass the `-agentlib:jdwp` JVM option to the forked JVM that runs Jetty, so that you can attach with a debugger. + +[NOTE] +==== +The `address` parameter of the `-agentlib:jdwp` command line option specifies the network address and port the Jetty JVM listens on for remote debugging. + +Please refer to the link:https://docs.oracle.com/en/java/javase/17/docs/specs/jpda/conninv.html[Java Debug Wire Protocol documentation] for additional information about the `-agentlib:jdwp` command line option and its parameters. +==== + +You can now enable the `remote-debug` Jetty module with the following command issued from the `$JETTY_BASE` directory: + +---- +$ java -jar $JETTY_HOME/start.jar --add-modules=server,remote-debug +---- + +The command above minimally adds a Jetty server without connectors (via the `server` Jetty module) and the `remote-debug` Jetty module, and produces the following `$JETTY_BASE` directory structure: + +[source,subs=normal] +---- +$JETTY_BASE +├── modules +│ └── remote-debug.mod +├── resources +│ └── jetty-logging.properties +└── start.d + ├── ##remote-debug.ini## + └── server.ini +---- + +You can easily disable the `remote-debug` Jetty module as explained in xref:og-start-configure-disable[this section]. + +Alternatively, you can enable the `remote-debug` module on the command line, as explained in xref:og-start-configure-enable-command-line[this section]. + +Starting the Jetty server with the `remote-debug` module enabled yields: + +[source,subs=quotes,options=nowrap] +---- +include::jetty[setupModules="src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod",setupArgs="--add-modules=server,remote-debug",highlight="5005"] +---- + +Note how the JVM is listening on port `5005` to allow remote debuggers to connect. + +If you want to avoid to fork a second JVM to pass the `-agentlib:jdwp` JVM option, please read xref:og-start-configure-dry-run[this section]. diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/troubleshooting.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/troubleshooting.adoc index 56d761c67ea..ff5241a6fab 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/troubleshooting.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/troubleshooting.adoc @@ -36,9 +36,9 @@ This is helpful because by reading the DEBUG logs you get a better understanding The Jetty artifact `jetty-slf4j-impl` is a SLF4J binding, that is the Jetty implementation of the SLF4J APIs, and provides a number of easy-to-use features to configure logging. The Jetty SLF4J binding only provides an appender that writes to `System.err`. -For more advanced configurations (for example, logging to a file), use link:http://logback.qos.ch[LogBack], or link:https://logging.apache.org/log4j/2.x/[Log4J2], or your preferred SLF4J binding. +For more advanced configurations (for example, logging to a file), use link:http://logback.qos.ch[LogBack], or link:https://logging.apache.org/log4j/2.x/[Log4j2], or your preferred SLF4J binding. -CAUTION: Only one binding can be present in the class-path or module-path. If you use the LogBack SLF4J binding or the Log4J2 SLF4J binding, remember to remove the Jetty SLF4J binding. +CAUTION: Only one binding can be present in the class-path or module-path. If you use the LogBack SLF4J binding or the Log4j2 SLF4J binding, remember to remove the Jetty SLF4J binding. The Jetty SLF4J binding reads a file in the class-path (or module-path) called `jetty-logging.properties` that can be configured with the logging levels for various logger categories: