* Issue #7299 - Enabling the logging-logback module prevents eclipse remote debugging. Added documentation as discussed in the issue. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
GitHub
parent
ce6e495c34
commit
528ac643ac
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
[description]
|
||||
Enables remote debugging
|
||||
|
||||
[exec]
|
||||
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
|
||||
|
|
@ -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].
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue