Package org.eclipse.jetty.server

Class CustomRequestLog

java.lang.Object
org.eclipse.jetty.util.component.AbstractLifeCycle
org.eclipse.jetty.util.component.ContainerLifeCycle
org.eclipse.jetty.server.CustomRequestLog
All Implemented Interfaces:
RequestLog, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle
@ManagedObject("Custom format request log") public class CustomRequestLog extends ContainerLifeCycle implements RequestLog

A flexible RequestLog, which produces log strings in a customizable format.

The Logger takes a format string where request characteristics can be added using "%" format codes which are replaced by the corresponding value in the log output.

The terms server, client, local and remote are used to refer to the different addresses and ports which can be logged. Server and client refer to the logical addresses which can be modified in the request headers. Where local and remote refer to the physical addresses which may be a proxy between the end-user and the server.

Format codes are specified with the syntax %MODIFIERS{PARAM}CODE as follows:

MODIFIERS
Optional list of comma separated HTTP status codes which may be preceded by a single "!" to indicate negation. If the status code is not in the list the literal string "-" will be logged instead of the resulting value from the percent code.
{PARAM}
Parameter string which may be optional depending on the percent code used.
CODE
A one or two character code specified by the table of format codes below.
Format Codes
Format String Description
X

The X character.
%%

The percent character.
%{format}a

The address or host name.

Valid format values are: "server", "client", "local", "remote". The format parameter is optional and defaults to "server".

Values "server" and "client" are the logical addresses which can be modified in the request headers, while "local" and "remote" are the physical addresses so may be the addresses of a proxy between the end-user and the server.
%{format}p

The port.

Valid format values are: "server", "client", "local", "remote". The format parameter is optional and defaults to "server".

Values "server" and "client" are the logical ports which can be modified in the request headers, while "local" and "remote" are the physical ports so may be the ports of a proxy between the end-user and the server.
%{CLF}I

The size of request in bytes, excluding HTTP headers.

The parameter is optional. When the parameter value is "CLF" the Common Log Format is used, i.e. a - rather than a 0 when no bytes are present.
%{CLF}O

The size of response in bytes, excluding HTTP headers.

The parameter is optional. When the parameter value is "CLF" the Common Log Format is used, i.e. a - rather than a 0 when no bytes are present.
%{CLF}S

The bytes transferred (received and sent). This is the combination of %I and %O.

The parameter is optional. When the parameter value is "CLF" the Common Log Format is used, i.e. a - rather than a 0 when no bytes are present.
%{VARNAME}C

The value of the request cookie VARNAME.

The parameter is optional. Only version 0 cookies are fully supported. When the parameter is missing, all request cookies will be logged.
%D

The time taken to serve the request, in microseconds.
%{VARNAME}e

The value of the environment variable VARNAME.
%f

The file system path of the requested resource.
%H

The name and version of the request protocol, such as "HTTP/1.1".
%{VARNAME}i

The value of the VARNAME request header.
%k

The number of requests handled on a connection.

The initial request on a connection yields a value 0, the first request after the initial on the same connection yields the value 1, the second request on the same connection yields the value 2, etc.
%m

The HTTP request method.
%{VARNAME}o

The value of the VARNAME response header.
%q

The query string, prepended with a ? if a query string exists, otherwise an empty string.
%r

First line of an HTTP/1.1 request (or equivalent information for HTTP/2 or later).
%R

The name of the Handler or Servlet generating the response (if any).
%s

The HTTP response status code.
%{format|timeZone|locale}t

The time at which the request was received.

The parameter is optional and may have the following values: {format}, {format|timeZone} or {format|timeZone|locale}.

format
Default is e.g. [18/Sep/2011:19:18:28 -0400] where the last number indicates the timezone offset from GMT. Must be in a format supported by the java.time package.
timeZone
Default is GMT. Must be in a format supported by the java.time package.
locale
Default is the JVM default locale. Must be in a format supported by java.util.Locale.forLanguageTag().
%{UNIT}T

The time taken to serve the request.

The parameter UNIT is optional and defaults to "s". The parameter UNIT indicates the unit of time: "s" for seconds, "ms" for milliseconds, "us" for microseconds. %{us}T is identical to %D.
%{d}u

The remote user if the request was authenticated with servlet authentication.

May be an invalid value if response status code (%s) is 401 (unauthorized).

The parameter is optional. When the parameter value is "d", deferred authentication will also be checked.
%U

The URL path requested, not including any query string.
%X

The connection status when response is completed:

X
The connection is aborted before the response completed.
+
The connection may be kept alive after the response is sent.
-
The connection will be closed after the response is sent.
%{VARNAME}ti

The value of the VARNAME request trailer.
%{VARNAME}to

The value of the VARNAME response trailer.
%{OPTION}uri

The request URI.

The parameter is optional and may have the be one of the following options:

%uri
The entire request URI.
%{-query}uri
The entire request URI without the query.
%{-path,-query}uri
The request URI without path or query (so just `scheme://authority`).
%{scheme}uri
The scheme of the request URI.
%{authority}uri
The authority of the request URI.
%{path}uri
The path of the request URI.
%{query}uri
The query of the request URI.
%{host}uri
The host of the request URI.
%{port}uri
The port of the request URI.
%{attributeName}attr

The value of the request attribute with the given name.

  • Field Details

  • Constructor Details

    • CustomRequestLog

      public CustomRequestLog()

    • CustomRequestLog

      public CustomRequestLog(String file)

    • CustomRequestLog

      public CustomRequestLog(String file, String format)

    • CustomRequestLog

      public CustomRequestLog(RequestLog.Writer writer, String formatString)

  • Method Details

    • setFilter

      public void setFilter(BiPredicate<Request,Response> filter)
      This allows you to set a custom filter to decide whether to log a request or omit it from the request log. This filter is evaluated after path filtering is applied from setIgnorePaths(String[]).
      Parameters:
      filter - - a BiPredicate which returns true if this request should be logged.

    • getWriter

      @ManagedAttribute("The RequestLogWriter") public RequestLog.Writer getWriter()

    • log

      public void log(Request request, Response response)
      Specified by:
      log in interface RequestLog
      Parameters:
      request - The request to log.
      response - The response to log.

    • setIgnorePaths

      public void setIgnorePaths(String[] ignorePaths)
      Set request paths that will not be logged.
      Parameters:
      ignorePaths - array of request paths

    • getIgnorePaths

      public String[] getIgnorePaths()
      Retrieve the request paths that will not be logged.
      Returns:
      array of request paths

    • getFormatString

      @ManagedAttribute("format string") public String getFormatString()
      Retrieve the format string.
      Returns:
      the format string

    • doStart

      protected void doStart() throws Exception
      Set up request logging and open log file.
      Overrides:
      doStart in class ContainerLifeCycle
      Throws:
      AbstractLifeCycle.StopException - If thrown, the lifecycle will immediately be stopped.
      Exception - If there was a problem starting. Will cause a transition to FAILED state
      See Also: