Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/jetty-9.4.x' into jetty-9.4.x-52…
Browse files Browse the repository at this point in the history 
…01-QueuedThreadPoolDump
  • Loading branch information
@lachlan-roberts
lachlan-roberts committed Sep 3, 2020
2 parents 85c8c65 + a676bdd commit 26ae875
Show file tree
Hide file tree
Showing 29 changed files with 1,161 additions and 1,033 deletions.
2 changes: 1 addition & 1 deletion jetty-documentation/src/main/asciidoc/administration/logging/chapter.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,4 @@ include::default-logging-with-stderrlog.adoc[]
include::configuring-jetty-request-logs.adoc[]
include::configuring-logging-modules.adoc[]
include::example-logback-centralized-logging.adoc[]
include::dump-tool.adoc[]
include::jetty-server-dump.adoc[]
837 changes: 0 additions & 837 deletions jetty-documentation/src/main/asciidoc/administration/logging/dump-tool.adoc
View file

This file was deleted.

189 changes: 189 additions & 0 deletions ...y-documentation/src/main/asciidoc/administration/logging/jetty-server-dump.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
// ========================================================================
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v1.0
// and Apache License v2.0 which accompanies this distribution.
//
// The Eclipse Public License is available at
// http://www.eclipse.org/legal/epl-v10.html
//
// The Apache License v2.0 is available at
// http://www.opensource.org/licenses/apache2.0.php
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
//

[[jetty-server-dump]]
=== Jetty Server Dump

The dump feature in Jetty provides a snapshot of the bean containment tree of the main Jetty components together with a summary of their configuration. This includes threadpool, connectors, contexts, webapplications, servlets and so forth.

[[configuring-dump-feature]]
==== Configuring the Jetty Server Dump

You can request that Jetty do a dump immediately after starting and just before stopping by calling the appropriate setters on the `Server` instance.
For embedded usage this can be used by calling the setters directly.
```java
server.setDumpAfterStart(true);
server.setDumpBeforeStop(true);
```

Standalone Jetty uses two properties to control this behaviour which are referenced in `jetty.xml` to call these setters.
These properties are `jetty.server.dumpAfterStart` and `jetty.server.dumpBeforeStop`.

These can be temporarily enabled by supplying these properties as command line arguments,
or they can be enabled via the `server.ini` file (see xref:quick-start-configure[]).
```
java -jar $JETTY_HOME/start.jar jetty.server.dumpAfterStart=true jetty.server.dumpBeforeStop=true
```

[[extra-threadpool-info]]
==== Extra ThreadPool Information

To get maximum detail from the `QueuedThreadPool` in the dump, you need to `setDetailDump(true)` on any instances of `QueuedThreadPool` you are using.
This extra detail in the detailed dump consists of full stack traces for every running thread, and a list of queued jobs waiting to be run.

For embedded usage this can be used by calling the setters directly.
```java
threadPool.setDetailedDump(true);
```

For standalone jetty you can enable the `threadpool` module and configure the `jetty.threadPool.detailedDump` property.
See xref:startup-modules[] for information on how to enable a module.
This same property can also be set via the command line the same as the server dump property.

[[dump-tool-via-jmx]]
==== Using the Dump Feature via JMX

The `dump` method is on the Server instance and many of its nested components (Handlers, Connectors, and so forth).
Dumps may be obtained by calling these methods either in code or via JMX (see xref:using-jmx[]).

The Server MBean has a `dump()` method, which dumps everything, plus a `dumpStdErr()` operation that dumps to StdErr rather than replying to JConsole.

[[examing-jetty-distro-dump]]
==== Explanation of the Dump Key

- `+- bean` is a java POJO that is contained by the parent object as a bean added with the addBean method.
- `+= managed` is a bean that is also a LifeCycle that is started and stopped with the parent object.
- `+~ unmanaged` is a bean that is also a LifeCycle that is started and stopped with the parent object. It is typically shared with other objects (hence its children are not dumped).
- `+? auto` is a bean that has been added to an unstarted parent. If it is a LifeCycle that is not started when the parent is started, then it is started and becomes a managed bean, otherwise it becomes either unmanaged or just a bean.
- `+: iterable` is an object that is contained within an iterable field of the parent (eg a list, set etc).
- `+] array` is an object that is contained within an array field of the parent.
- `+@ map` is an object that is contained within an map field of the parent.
- `+> undefined` is an object that is contained within the parent by an undefined relationship.

==== Jetty Server Dump Example

This is a dump of the OneServletContext embedded example with extra threadpool information:

....
Server@59906517{STARTED}[9.4.32-SNAPSHOT] - STARTED
+= QueuedThreadPool[qtp1740189450]@67b92f0a{STARTED,8<=8<=200,i=5,r=4,q=0}[ReservedThreadExecutor@77e4c80f{s=0/4,p=0}] - STARTED
| += ReservedThreadExecutor@77e4c80f{s=0/4,p=0} - STARTED
| +> threads size=8
| | +> 12 qtp1740189450-12 SELECTING RUNNABLE 5
| | +> 14 qtp1740189450-14-acceptor-0@4c78251c-ServerConnector@76707e36{HTTP/1.1, (http/1.1)}{0.0.0.0:8080} ACCEPTING RUNNABLE 3
| | +> 16 qtp1740189450-16 IDLE TIMED_WAITING 5
| | +> 18 qtp1740189450-18 IDLE TIMED_WAITING 5
| | +> 15 qtp1740189450-15 SELECTING RUNNABLE 5
| | +> 19 qtp1740189450-19 IDLE TIMED_WAITING 5
| | +> 17 qtp1740189450-17 IDLE TIMED_WAITING 5
| | +> 13 qtp1740189450-13 IDLE TIMED_WAITING 5
| +> jobs size=0
+= ServerConnector@76707e36{HTTP/1.1, (http/1.1)}{0.0.0.0:8080} - STARTED
| +~ Server@59906517{STARTED}[9.4.32-SNAPSHOT] - STARTED
| +~ QueuedThreadPool[qtp1740189450]@67b92f0a{STARTED,8<=8<=200,i=5,r=4,q=0}[ReservedThreadExecutor@77e4c80f{s=0/4,p=0}] - STARTED
| += ScheduledExecutorScheduler@7fe8ea47{STARTED} - STARTED
| +- org.eclipse.jetty.io.ArrayByteBufferPool@226a82c4
| += HttpConnectionFactory@711f39f9[HTTP/1.1] - STARTED
| | +- HttpConfiguration@731f8236{32768/8192,8192/8192,https://:0,[]}
| | +> customizers size=0
| | +> formEncodedMethods size=2
| | | +> POST
| | | +> PUT
| | +> outputBufferSize=32768
| | +> outputAggregationSize=8192
| | +> requestHeaderSize=8192
| | +> responseHeaderSize=8192
| | +> headerCacheSize=1024
| | +> secureScheme=https
| | +> securePort=0
| | +> idleTimeout=-1
| | +> blockingTimeout=-1
| | +> sendDateHeader=true
| | +> sendServerVersion=true
| | +> sendXPoweredBy=false
| | +> delayDispatchUntilContent=true
| | +> persistentConnectionsEnabled=true
| | +> maxErrorDispatches=10
| | +> minRequestDataRate=0
| | +> minResponseDataRate=0
| | +> cookieCompliance=RFC6265
| | +> setRequestCookieCompliance=RFC6265
| | +> notifyRemoteAsyncErrors=true
| | +> relativeRedirectAllowed=false
| += SelectorManager@ServerConnector@76707e36{HTTP/1.1, (http/1.1)}{0.0.0.0:8080} - STARTED
| | += ManagedSelector@564718df{STARTED} id=0 keys=0 selected=0 updates=0 - STARTED
| | | += EatWhatYouKill@51b7e5df/SelectorProducer@18a70f16/PRODUCING/p=false/QueuedThreadPool[qtp1740189450]@67b92f0a{STARTED,8<=8<=200,i=5,r=4,q=0}[ReservedThreadExecutor@77e4c80f{s=0/4,p=0}][pc=0,pic=0,pec=0,epc=0]@2020-08-26T08:51:02.711784+10:00 - STARTED
| | | | +- SelectorProducer@18a70f16
| | | | +~ QueuedThreadPool[qtp1740189450]@67b92f0a{STARTED,8<=8<=200,i=5,r=4,q=0}[ReservedThreadExecutor@77e4c80f{s=0/4,p=0}] - STARTED
| | | +> updates @ 2020-08-26T08:51:02.705944+10:00 size=0
| | | +> keys @ 2020-08-26T08:51:02.706914+10:00 size=0
| | += ManagedSelector@62e136d3{STARTED} id=1 keys=0 selected=0 updates=0 - STARTED
| | += EatWhatYouKill@c8e4bb0/SelectorProducer@6279cee3/PRODUCING/p=false/QueuedThreadPool[qtp1740189450]@67b92f0a{STARTED,8<=8<=200,i=5,r=4,q=0}[ReservedThreadExecutor@77e4c80f{s=0/4,p=0}][pc=0,pic=0,pec=0,epc=0]@2020-08-26T08:51:02.717119+10:00 - STARTED
| | | +- SelectorProducer@6279cee3
| | | +~ QueuedThreadPool[qtp1740189450]@67b92f0a{STARTED,8<=8<=200,i=5,r=4,q=0}[ReservedThreadExecutor@77e4c80f{s=0/4,p=0}] - STARTED
| | +> updates @ 2020-08-26T08:51:02.715887+10:00 size=0
| | +> keys @ 2020-08-26T08:51:02.716158+10:00 size=0
| +- sun.nio.ch.ServerSocketChannelImpl[/0:0:0:0:0:0:0:0:8080]
| +- qtp1740189450-14-acceptor-0@4c78251c-ServerConnector@76707e36{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
+= AttributeContainerMap@4206a205{size=0} - STARTED
+= o.e.j.s.ServletContextHandler@4ba2ca36{/,file:///tmp/,AVAILABLE} - STARTED
| += org.eclipse.jetty.server.session.SessionHandler2007331442==dftMaxIdleSec=-1 - STARTED
| | += ServletHandler@29ba4338{STARTED} - STARTED
| | | +> listeners ServletHandler@29ba4338{STARTED} size=2
| | | | +> ListenerHolder@57175e74{STARTED}: org.eclipse.jetty.embedded.OneServletContext$InitListener - STARTED
| | | | +> ListenerHolder@7bb58ca3{STARTED}: org.eclipse.jetty.embedded.OneServletContext$RequestListener - STARTED
| | | +> filters ServletHandler@29ba4338{STARTED} size=2
| | | | +> org.eclipse.jetty.embedded.OneServletContext$TestFilter-29b5cd00@29b5cd00==org.eclipse.jetty.embedded.OneServletContext$TestFilter,inst=true,async=true - STARTED
| | | | | +> org.eclipse.jetty.embedded.OneServletContext$TestFilter@c540f5a
| | | | +> org.eclipse.jetty.embedded.OneServletContext$TestFilter-7113b13f@7113b13f==org.eclipse.jetty.embedded.OneServletContext$TestFilter,inst=true,async=true - STARTED
| | | | +> org.eclipse.jetty.embedded.OneServletContext$TestFilter@770c2e6b
| | | +> filterMappings ServletHandler@29ba4338{STARTED} size=2
| | | | +> [/test/*]/[]/[REQUEST]=>org.eclipse.jetty.embedded.OneServletContext$TestFilter-29b5cd00
| | | | +> [*.test]/[]/[REQUEST, ASYNC]=>org.eclipse.jetty.embedded.OneServletContext$TestFilter-7113b13f
| | | +> servlets ServletHandler@29ba4338{STARTED} size=3
| | | | +> org.eclipse.jetty.embedded.HelloServlet-6b57696f@99887e98==org.eclipse.jetty.embedded.HelloServlet,jsp=null,order=-1,inst=false,async=true - STARTED
| | | | | +> class org.eclipse.jetty.embedded.HelloServlet
| | | | +> debug@5b09653==org.eclipse.jetty.embedded.DumpServlet,jsp=null,order=-1,inst=false,async=true - STARTED
| | | | | +> class org.eclipse.jetty.embedded.DumpServlet
| | | | +> org.eclipse.jetty.servlet.DefaultServlet-38bc8ab5@f1bd2681==org.eclipse.jetty.servlet.DefaultServlet,jsp=null,order=-1,inst=false,async=true - STARTED
| | | | +> class org.eclipse.jetty.servlet.DefaultServlet
| | | +> servletMappings ServletHandler@29ba4338{STARTED} size=4
| | | +> [/hello/*]=>org.eclipse.jetty.embedded.HelloServlet-6b57696f
| | | +> [/dump/*]=>debug
| | | +> [*.dump]=>debug
| | | +> [/]=>org.eclipse.jetty.servlet.DefaultServlet-38bc8ab5
| | += org.eclipse.jetty.server.session.DefaultSessionCache@6328d34a[evict=-1,removeUnloadable=false,saveOnCreate=false,saveOnInactiveEvict=false] - STARTED
| | | += org.eclipse.jetty.server.session.NullSessionDataStore@145eaa29[passivating=false,graceSec=3600] - STARTED
| | +~ DefaultSessionIdManager@15bb6bea{STARTED}[worker=node0] - STARTED
| +> No ClassLoader
| +> eventListeners o.e.j.s.ServletContextHandler@4ba2ca36{/,file:///tmp/,AVAILABLE} size=2
| | +> org.eclipse.jetty.embedded.OneServletContext$InitListener@8b96fde
| | +> org.eclipse.jetty.embedded.OneServletContext$RequestListener@2d2e5f00
| +> handler attributes o.e.j.s.ServletContextHandler@4ba2ca36{/,file:///tmp/,AVAILABLE} size=1
| | +> org.eclipse.jetty.server.Executor=QueuedThreadPool[qtp1740189450]@67b92f0a{STARTED,8<=8<=200,i=5,r=4,q=0}[ReservedThreadExecutor@77e4c80f{s=0/4,p=0}]
| +> context attributes o.e.j.s.ServletContextHandler@4ba2ca36{/,file:///tmp/,AVAILABLE} size=2
| | +> org.eclipse.jetty.util.DecoratedObjectFactory=org.eclipse.jetty.util.DecoratedObjectFactory[decorators=1]
| | +> X-Init=true
| +> initparams o.e.j.s.ServletContextHandler@4ba2ca36{/,file:///tmp/,AVAILABLE} size=0
+= ErrorHandler@2ea6137{STARTED} - STARTED
+= DefaultSessionIdManager@15bb6bea{STARTED}[worker=node0] - STARTED
| += HouseKeeper@3439f68d{STARTED}[interval=660000, ownscheduler=true] - STARTED
+> jdk.internal.loader.ClassLoaders$AppClassLoader@2c13da15
+> jdk.internal.loader.ClassLoaders$PlatformClassLoader@41ee392b
key: +- bean, += managed, +~ unmanaged, +? auto, +: iterable, +] array, +@ map, +> undefined
....
57 changes: 53 additions & 4 deletions jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ When executed `start.jar` performs the following actions:
3. Uses default behavior of `java.io.File` (Relative to `System.getProperty` ("user.dir") and then as absolute file system path).
* Loads any dependent modules (merges XXNK, library, and properties results with active command line).
* Builds out server classpath.
* Determines run mode:
* Determines run mode as one of:
** Shows informational command line options and exit.
** Executes Jetty normally, waits for Jetty to stop.
** Executes a forked JVM to run Jetty in, waits for forked JVM to exit.
Expand All @@ -89,17 +89,44 @@ Lists the resolved configuration that will start Jetty.
* Server classpath
* Server XML configuration files
--dry-run::
Prints the resolved command line that `start.jar` should use to start a forked instance of Jetty.
Print the command line that the start.jar generates, then exit. This may be used to generate command lines when the start.ini includes -X or -D arguments:
....
$ java -jar start.jar --dry-run > jetty.sh
$ . jetty.sh
....
--dry-run=<parts>::
Print specific parts of the command line. The parts are a comma separated list of:

* "java" - the JVM to run
* "opts" - the JVM options (eg -D and -X flags)
* "path" - the JVM class path or JPMS modules options
* "main" - the main class to run
* "args" - the arguments passed to the main class

It is possible to decompose the start command:
....
$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
....
Alternatively to create an args file for java:
....
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args
....
--exec::
Starts a forked instance of Jetty.
Forces the start to use a forked instance of java to run Jetty.
Some modules include `--exec` in order to set java command line options.
Some start options, such as `--jpms` also imply `--exec`
--exec-properties=<filename>::
Assign a fixed name to the file used to transfer properties to the sub process.
This allows the generated properties file to be saved and reused.
Without this option, a temporary file is used.
--commands=<filename>::
Instructs `start.jar` to use each line of the specified file as arguments on the command line.

===== Debugg and Start Logging
===== Debug and Start Logging

--debug::
Enables debugging output of the startup procedure.
Expand Down Expand Up @@ -275,3 +302,25 @@ If you have a need for a shaded version of `start.jar` (such as for Gradle), you
<classifier>shaded</classifier>
</dependency>
....

==== Start.jar without exec or forking.

Some Jetty modules include the `--exec` option so that java command line options can be set.
Also some `start.jar` options (eg. `--jpms`) include an implicit `--exec`.
To start jetty without forking a new JVM instance from the start JVM, the `--dry-run` option can be used to generate a command line:
....
$ CMD=$(java -jar start.jar --dry-run)
$ $CMD
....
It is possible to decompose the start command so that it can be modified:
....
$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
....
Alternatively to create an args file for java:
....
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args
....
19 changes: 19 additions & 0 deletions ...cumentation/src/main/asciidoc/development/handlers/writing-custom-handlers.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,25 @@ This is typically used to pass a request to a link:{JDURL}/org/eclipse/jetty/ser
* link:{JDURL}/org/eclipse/jetty/server/handler/HandlerList.html[`HandlerList`] - A list of handlers that are called in turn until the request state is set as handled.
* link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandlerCollection.html[`ContextHandlerCollection`] - A collection of Handlers, of which one is selected by best match for the context path.

[[injecting-handlers]]
==== Injecting Handlers

The `Handler` needs to be added to the server classpath as described in xref:startup-classpath[].
Then it can be added to the server, either by overriding some existing XML configuration files such as `jetty.xml` as shown below, or by defining a custom module as described in xref:custom-modules[].

[source, xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="setHandler">
<Arg>
<New id="myCustomJettyHandler" class="com.my.handler.CustomJettyHandler" />
</Arg>
</Call>
</Configure>
----

[[more-about-handlers]]
==== More About Handlers

Expand Down
Loading

0 comments on commit 26ae875

Please sign in to comment.