HTTP access logging

You can configure access log settings for HTTP endpoints. An HTTP access log contains a record of all inbound client requests handled by those endpoints.

You can enable access logging in the Open Liberty server in two modes: a single log for multiple endpoints or one log for each endpoint. If you do not specify attributes, the defaults are used. To see a list of the default attributes, see httpAccessLogging.

HTTP access log settings

For a basic configuration, you can enable HTTP access logging by adding the accessLogging element to an httpEndpoint. When no attributes are specified, the default access logging settings are used.

<httpEndpoint id="defaultHttpEndpoint" httpPort="9080" httpsPort="9443">
    <accessLogging/>
</httpEndpoint>

You can configure HTTP access log settings either for multiple endpoints that share common log settings or for individual endpoints.

Settings for a common log

To enable logging for multiple endpoints with common settings, include httpAccessLogging as a top-level element in your server.xml file. Then reference this element from multiple httpEndpoint elements, as shown in the following example.

<httpAccessLogging id="accessLogging"/>
<httpEndpoint id="defaultHttpEndpoint" accessLoggingRef="accessLogging" httpPort="9080" httpsPort="9443"/>
<httpEndpoint id="otherHttpEndpoint" accessLoggingRef="accessLogging" httpPort="9081" httpsPort="9444"/>

Settings for distinct logs for each endpoint

To enable logging for individual endpoints, use an accessLogging child element and specify a file path that does not conflict with other logs, as shown in the following example.

<httpEndpoint id="defaultHttpEndpoint" httpPort="9080" httpsPort="9443">
    <accessLogging filepath="${server.output.dir}/logs/http_defaultEndpoint_access.log"/>
</httpEndpoint>

HTTP access log format

Use the accessLogFormat property to specify the format of information you want to include in the NCSA access log for an HTTP transport channel. The value for this property is a space-separated list of options.

Specify the log format string with the logFormat attribute of httpAccessLogging or accessLogging elements in the server.xml file, as shown in the following examples.

In the following server.xml file example, the logFormat attribute for the httpAccessLogging element specifies the log format string. Multiple endpoints can specify this string by referencing the accessLogging configuration ID.

<httpAccessLogging id="accessLogging" logFormat='%h %u %{t}W "%r" %s %b %D %{R}W'/>

In the following server.xml file example, the logFormat attribute for the accessLogging subelement specifies the log format string for a specific endpoint that is defined in the httpEndpoint element.

<httpEndpoint id="defaultHttpEndpoint" httpPort="9080" httpsPort="9443">
   <accessLogging filepath="${server.output.dir}/logs/http_defaultEndpoint_access.log"
                  logFormat='%h %i %u %t "%r" %s %b %D %{R}W' />
</httpEndpoint>

The following table lists the available log format options.

Log format option Description

Log format option	Description
%a	The remote IP address.
%A	The local IP address.
%b	The response size in bytes excluding the headers.
%B	The response size in bytes excluding the headers. If no value is found, `0` is printed instead of `-`.
%{CookieName}C or %C	The request cookie that is specified within the brackets. If the brackets are not included, all request cookies are printed.
%D	The elapsed time of the request, in microseconds.
%h	The remote host.
%i or %{HeaderName}i	The `HeaderName` header value from the request.
%m	The request method.
%o or %{HeaderName}o	The `HeaderName` header value from the response.
%q	The query string, with any password masked.
%r	The first line of the request.
%{remote}p	The ephemeral port of the client that made the request.
%{R}W	The service time of the request, from the moment the request is received until the first set of bytes of the response is sent; millisecond accuracy, microsecond precision.
%s	The status code of the response.
%t	The start time of the request, in NCSA format.
%{t}W	The end time of the request, in NCSA format.
%u	The remote user according to the Open Liberty-specific `$WSRU` header.
%U	The URL path, not including the query string.
%I and %O	Liberty does not support the `%I` and `%O` Apache httpd tokens, which represent the total bytes received and sent, including headers. When you use these tokens, Liberty generates a First Failure Data Capture (FFDC) error at startup: `IllegalArgumentException: Config: invalid format segment: %I` or `IllegalArgumentException: Config: invalid format segment: %O`. Instead, use `%b`, which logs the response size in bytes, excluding response headers.

The remote IP address.

The local IP address.

The response size in bytes excluding the headers.

The response size in bytes excluding the headers. If no value is found, 0 is printed instead of -.

%{CookieName}C or %C

The request cookie that is specified within the brackets. If the brackets are not included, all request cookies are printed.

The elapsed time of the request, in microseconds.

The remote host.

%i or %{HeaderName}i

The HeaderName header value from the request.

The request method.

%o or %{HeaderName}o

The HeaderName header value from the response.

The query string, with any password masked.

The first line of the request.

%{remote}p

The ephemeral port of the client that made the request.

%{R}W

The service time of the request, from the moment the request is received until the first set of bytes of the response is sent; millisecond accuracy, microsecond precision.

The status code of the response.

The start time of the request, in NCSA format.

%{t}W

The end time of the request, in NCSA format.

The remote user according to the Open Liberty-specific $WSRU header.

The URL path, not including the query string.

%I and %O

Liberty does not support the %I and %O Apache httpd tokens, which represent the total bytes received and sent, including headers. When you use these tokens, Liberty generates a First Failure Data Capture (FFDC) error at startup: IllegalArgumentException: Config: invalid format segment: %I or IllegalArgumentException: Config: invalid format segment: %O. Instead, use %b, which logs the response size in bytes, excluding response headers.

Each option can be enclosed in quotation marks, but the quotation marks are not required. Unless otherwise noted, a value of - is printed for an option if the requested information cannot be obtained for that option.

The order in which you specify the options determines the format of this information in the log. For example, you might specify the following options as the value for the accessLogFormat property:

 %h %i %u %t "%r" %s %b %D %{R}W

Based on this setting, the NCSA access log includes the following information for each request in the specified order:

The remote host
The HeaderName header value from the request
The remote user according to the Open Liberty-specific $WSRU header
The NCSA format of the start time of the request
The first line of the request
The status code of the response
The response size in bytes excluding headers
The elapsed time of the request in microseconds, end-to-end, including client and network time
The elapsed time in microseconds until the first bytes of the response are sent. This value is often a close approximation of application response time.

Time-based HTTP access log rollover

You can enable time-based periodic rollover of your HTTP access log file by specifying a log rollover start time and a rollover interval duration.

For example, a server with a rollover start time of midnight and a rollover interval of 1 day rolls over the HTTP access log once every day at midnight.

Enable time-based rollover of your HTTP access log file by using the rolloverStartTime and rolloverInterval attributes of the httpAccessLogging or accessLogging elements in the server.xml file. The following table lists the two attributes, their respective descriptions, and their permitted values.

Time-based log rollover attribute Description

Time-based log rollover attribute	Description
`rolloverStartTime`	Use this setting alone or with the `rolloverInterval` attribute to enable time-based log rollover for your HTTP access log file. This setting specifies the scheduled time of day for logs to first roll over. The `rolloverInterval` setting duration begins at `rolloverStartTime`. Valid values follow a 24-hour ISO-8601 date-time format of HH:MM, where 00:00 represents midnight. Padding zeros are required. If the `rolloverInterval` attribute is specified, the default value of the `rolloverStartTime` attribute is 00:00, midnight.
`rolloverInterval`	Use this setting alone or with the `rolloverStartTime` attribute to enable time-based log rollover for your HTTP access log file. This setting specifies the time interval between log rollovers, in minutes if a unit of time is not specified. Specify a positive integer followed by a unit of time, which can be days (d), hours (h), or minutes (m). For example, specify 5 hours as 5h. You can include multiple values in a single entry. For example, 1d5h is equivalent to 1 day and 5 hours. If the `rolloverStartTime` attribute is specified, the default value of the `rolloverInterval` attribute is 1 day.

rolloverStartTime

Use this setting alone or with the rolloverInterval attribute to enable time-based log rollover for your HTTP access log file. This setting specifies the scheduled time of day for logs to first roll over. The rolloverInterval setting duration begins at rolloverStartTime. Valid values follow a 24-hour ISO-8601 date-time format of HH:MM, where 00:00 represents midnight. Padding zeros are required. If the rolloverInterval attribute is specified, the default value of the rolloverStartTime attribute is 00:00, midnight.

rolloverInterval

Use this setting alone or with the rolloverStartTime attribute to enable time-based log rollover for your HTTP access log file. This setting specifies the time interval between log rollovers, in minutes if a unit of time is not specified. Specify a positive integer followed by a unit of time, which can be days (d), hours (h), or minutes (m). For example, specify 5 hours as 5h. You can include multiple values in a single entry. For example, 1d5h is equivalent to 1 day and 5 hours. If the rolloverStartTime attribute is specified, the default value of the rolloverInterval attribute is 1 day.

The following examples show how to configure time-based periodic rollover by using the httpAccessLogging and accessLogging elements. The rolloverStartTime attribute is set to midnight and the rolloverInterval attribute is set to 1 day.

In the following server.xml file example, the rolloverStartTime and rolloverInterval attributes for the httpAccessLogging element specify the log rollover start time and interval for multiple endpoints that reference the accessLogging configuration ID.

<httpAccessLogging id="accessLogging" rolloverStartTime="00:00" rolloverInterval="1d"/>

In the following server.xml file example, attributes for the accessLogging subelement configure time-based rollover for a specific endpoint that is defined in the httpEndpoint element. The rolloverStartTime and rolloverInterval attributes specify the log rollover start time and interval for the endpoint.

<httpEndpoint id="defaultHttpEndpoint" httpPort="9080" httpsPort="9443">
   <accessLogging filepath="${server.output.dir}/logs/http_defaultEndpoint_access.log"
                 rolloverStartTime="00:00" rolloverInterval="1d" />
</httpEndpoint>