Merge branch 'jetty-9.4.x'

jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc

@@ -23,44 +23,42 @@ There is one entry per request received, and commonly in the standard NCSA forma
 [[constructing-request-log-entry]]
 ==== Constructing a Request Log Entry
 
-A standard request log entry includes the client IP address, date, method, URL, result, size, referrer, and user agent, for example:
+A standard request log entry includes the client IP address, date, method, URL, result, size, referrer, user agent and latency for example:
 
 ....
 123.4.5.6 - - [27/Aug/2004:10:16:17 +0000]
   "GET /jetty/tut/XmlConfiguration.html HTTP/1.1"
   200 76793 "http://localhost:8080/jetty/tut/logging.html"
-  "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040614 Firefox/0.8"
+  "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040614 Firefox/0.8" 342
 ....
 
 [[implementing-request-log]]
 ==== Implementing a Request Log
 
-Jetty provides an implementation called _`NCSARequestLog`_ which supports the NCSA format in files that you can roll over on a daily basis.
+Jetty provides an implementation called `NCSARequestLog` which supports the NCSA format in files that will roll over on a daily basis.
 
 The http://logback.qos.ch/[Logback Project] offers http://logback.qos.ch/access.html[another implementation] of a `RequestLog` interface, providing rich and powerful HTTP-access log functionality.
 
 If neither of these options meets your needs, you can implement a custom request logger by implementing Jetty's link:{JDURL}/org/eclipse/jetty/server/RequestLog.html[`RequestLog.java`] interface and plugging it in similar to the `NCSARequestLog`, as shown below.
 
 [[configuring-request-log]]
-==== Configuring a Request Log
+==== Configuring the Request Log module
 
-To configure a single request log for the entire Jetty Server instance:
+To enable the Request Log module for the entire server via the Jetty distribution, it first needs to be enabled on the command line:
 
-[source, xml, subs="{sub-order}"]
+[source, screen, subs="{sub-order}"]
 ----
-<Configure id="Server" class="org.eclipse.jetty.server.Server">
+$ java -jar ../start.jar --add-to-startd=requestlog
-  <Set name="RequestLog">
+
-    <New id="RequestLog" class="org.eclipse.jetty.server.AsyncNCSARequestLog">
+INFO: requestlog      initialised in ${jetty.base}/start.d/requestlog.ini
-      <Set name="filename">/var/log/jetty/yyyy_mm_dd.request.log</Set>
+MKDIR: ${jetty.base}/logs
-      <Set name="append">true</Set>
+INFO: Base directory was modified
-      <Set name="extended">false</Set>
-      <Set name="LogTimeZone">GMT</Set>
-    </New>
-  </Set>
-</Configure>
 ----
 
-The equivalent code is:
+The above command will add a new `requestlog.ini` file to your `{$jetty.base}/start.d` directory.
+If you used `--add-to-start` it will append the configuration options for the module to the `start.ini` file located in your `{$jetty.base}` directory.
+
+The equivalent code for embedded usages of Jetty is:
 
 [source, java, subs="{sub-order}"]
 ----
@@ -68,12 +66,13 @@ NCSARequestLog requestLog = new NCSARequestLog("/var/logs/jetty/jetty-yyyy_mm_dd
 requestLog.setAppend(true);
 requestLog.setExtended(false);
 requestLog.setLogTimeZone("GMT");
+requestLog.setLogLatency(true);
 
 server.setRequestLog(requestLog);
 ----
 
-This configures a request log in `$JETTY_HOME/logs` with filenames including the date. 
+This configures a request log in `{$jetty.home}/logs` with filenames including the date.
-Old log files are kept for 90 days before being deleted. 
+By defaukt, log files are kept for 90 days before being deleted.
 Existing log files are appended to and the extended NCSA format is used in the GMT time zone.
 
 To examine many more configuration options, see link:{JDURL}/org/eclipse/jetty/server/NCSARequestLog.html[NCSARequestLog.java].
@@ -81,7 +80,7 @@ To examine many more configuration options, see link:{JDURL}/org/eclipse/jetty/s
 [[configuring-separate-request-log-for-web-application]]
 ==== Configuring a Separate Request Log For a Web Application
 
-To configure a separate request log for a web application, add the following to the context XML file.
+To configure a separate request log for specific a web application, add the following to the context XML file.
 
 [source, xml, subs="{sub-order}"]
 ----
@@ -97,6 +96,7 @@ To configure a separate request log for a web application, add the following to
             <Set name="LogTimeZone">GMT</Set>
             <Set name="retainDays">90</Set>
             <Set name="append">true</Set>
+            <Set name="LogLatency">true</Set>
           </New>
         </Set>
       </New>

jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc

@@ -95,6 +95,66 @@ include::screen-http-webapp-deploy-listconfig.adoc[]
 You now have a configured and functional server, albeit with no webapps deployed.
 At this point you can place a webapp (war file) in the `mybase/webapps/` directory and and start Jetty.
 
+[[startup-configuring-modules]]
+
+==== Configuring Modules
+
+Once a module has been enabled for the server, it can be further configured to meet your needs.
+This is done by editing the associated ini file for the module.
+If your server setup is using a centralized ini configuration, you will edit the `{$jetty.base}/server.ini` file.
+If you have elected to manage each module within it's own ini file, you can find these files in the `{$jetty.base}/start.d` directory.
+
+When a module is activated, a number of properties are set by default.
+To view these defaults, open up the associated ini file.
+Listed in the ini file is the associated module file and any properties that can be set.
+
+Below is an example of the `requestlog.ini` file:
+
+[source, screen, subs="{sub-order}"]
+....
+# ---------------------------------------
+# Module: requestlog
+--module=requestlog
+
+## Logging directory (relative to $jetty.base)
+# jetty.requestlog.dir=logs
+
+## File path
+# jetty.requestlog.filePath=${jetty.requestlog.dir}/yyyy_mm_dd.request.log
+
+## Date format for rollovered files (uses SimpleDateFormat syntax)
+# jetty.requestlog.filenameDateFormat=yyyy_MM_dd
+
+## How many days to retain old log files
+# jetty.requestlog.retainDays=90
+
+## Whether to append to existing file
+# jetty.requestlog.append=true
+
+## Whether to use the extended log output
+# jetty.requestlog.extended=true
+
+## Whether to log http cookie information
+# jetty.requestlog.cookies=true
+
+## Timezone of the log entries
+# jetty.requestlog.timezone=GMT
+
+## Whether to log LogLatency
+# jetty.requestlog.loglatency=false
+....
+
+The first lines name the module file being called (located in `{$jetty.home/modules}`).
+Subsequent lines list properties that can be changed as well as a description for each property.
+To edit a property, first un-comment the line by deleting the `#` at the start of the line, then make the change after `=` sign (such as changing a `true` value to `false`).
+
+[[startup-disable-module]]
+==== Disabling Modules
+
+Disabling a module is an easy process.
+To disable a module, comment out the `--module=` line in the associated ini file.
+Deleting the ini file associated with module is another option, but may not be practical in all situations.
+
 [[startup-listing-modules]]
 ==== Listing Available and Active Modules
 

jetty-server/src/main/config/etc/jetty-requestlog.xml

@@ -24,6 +24,7 @@
       <Set name="extended"><Property name="jetty.requestlog.extended" deprecated="requestlog.extended" default="false"/></Set>
       <Set name="logCookies"><Property name="jetty.requestlog.cookies" deprecated="requestlog.cookies" default="false"/></Set>
       <Set name="LogTimeZone"><Property name="jetty.requestlog.timezone" deprecated="requestlog.timezone" default="GMT"/></Set>
+      <Set name="LogLatency"><Property name="jetty.requestlog.loglatency" default="false"/></Set>
     </New>
   </Set>
 </Configure>

jetty-server/src/main/config/modules/requestlog.mod

@@ -34,3 +34,6 @@ logs/
 
 ## Timezone of the log entries
 # jetty.requestlog.timezone=GMT
+
+## Whether to log LogLatency
+# jetty.requestlog.loglatency=false