Access log format

This article explains how to specify a certain access log format.

1 Introduction

    The goal of this article is to explain how an access log can be formatted using the options available for this purpose.

    The article requires basic knowledge of access logs.

2 Modifying

    This section will explain where to put the access log format tag and the syntax for describing the wanted output.

    This section involves the following steps:

    2.1 Step 1: Where is this configured?

      The access log format is specified as a parameter to the access-log tag in the web-site tag of the web-site.xml-file.

      A normal entry looks something like the following:


          <web-site display-name="Default Web Site" port="80">
              ...
              <access-log path="../log/default-web-access.log" />
              ...
          </web-site>
      Listing 1: Example log entry in web-site.xml

      Go here to see the DTD comment for the access-log tag.

      As no format parameter is given in the above example, the default format is used. The default format looks like:


          $ip - - - [$time] '$request' $status $size
      Listing 2. The default log format

      The web-site.xml for the Default Web Application is located at /orion/config/default-web-site.xml

    2.2 Step 2: Expressing the log format

      The log format attribute might hold valid XML characters and the variables defined in step 3 below.

      If the log format should start with the request path, the entry would look like in Listing 3 below:


          <web-site display-name="Default Web Site" port="80">
              ...
              <access-log
                  path="../log/default-web-access.log"
                  format="$path $ip - - - [$time] '$request' $status $size"
              >
              ...
              </web-site>
      Listing 3: Example log format where the default log format has been prefixed with the request path

      Go here to see the DTD comment for the access-log tag.

    2.3 Step 3: Available variables

      The following variables are available:

        $time - The time the request was made

        $request - First line of request

        $ip - Remote IP-address

        $host - Remote Host-name

        $path - The URL path requested, not including any query string.

        $size - Bytes sent, excluding HTTP headers. In CLF format i.e. a '-' rather than a 0 when no bytes are sent.

        $method - The request method

        $protocol - The request protocol

        $user - Remote user (from auth)

        $status - Status

        $referer - The referencing page

        $agent - The User-agent

        $mime - The mime type

        $cookie:[name] - The value of the specified cookie

        $header:[name] - The value of the specified header field

      As the format string is an attribute inside an XML document, the following reference types could come in handy:

        &quot; - "

        &lt; - <

        &gt; - >

        &#13; - CR

        &#59; - ;

        &amp; - &

        &apos; - '

3 Splitting the log

    This section will explain how to split the access log file into multiple files in order to make it easier to manage them.

    This section involves the following steps:

    3.1 Step 1: Setting the time-span for log files

      The access log file can be split into multiple files, each containing the logs of one day up to one month worth of log entries.

      The default value for an access log file is that there is one file containing all entries. This would be expressed in the following way in the web-site.xml-file:


          <web-site display-name="Default Web Site" port="80">
              ...
              <access-log
                  path="../log/default-web-access.log"
                  format="$path $ip - $user - [$time] '$request' $status $size"
                  split="none"
              >
              ...
          </web-site>
      Listing 4: Split usage example

      The web-site.xml for the Default Web Application is located at /orion/config/default-web-site.xml

      Go here to see the DTD comment for the access-log tag.

      The value of split above can be one of the following:

        none - Do not split the file.

        hour - Split the file on a hourly basis.

        day - Split the file on a daily basis.

        week - Split the file on a weekly basis.

        month - Split the file on a monthly basis.

      If you are using the split attribute with a value other than "none", it's important to also include the suffix attribute (described below) in order to avoid sublimal errors

    3.2 Step 2: Defining unique access log file names

      When splitting the access log, a filename suffix needs to be specified, to make sure that unique file names are generated for every log file

      The suffix attribute is stated as in the following example:


          <web-site display-name="Default Web Site" port="80">
              ...
              <access-log
                  path="../log/default-web-access.log"
                  format="$path $ip - $user - [$time] '$request' $status $size"
                  split="month"
                  suffix="-yyyy-MM"
              >
              ...
          </web-site>
      Listing 5: Log file suffix usage example

      The attribute suffix takes a String representing a java.text.SimpleDateFormat pattern.

      The example given above would create one log file per month and making sure that the files are not overwritten the following year.

      The default value of the suffix attribute depends on the value of the split attribute.

      If split has a value of "none", the default value for suffix will be "" (empty).

      If split has a value of "hour", the default value for suffix will be "-yyyy-MM-dd - HH".

      If split has a value of "day", the default value for suffix will be "-yyyy-MM-dd".

      If split has a value of "week", the default value for suffix will be "-yyyy-ww".

      If split has a value of "month", the default value for suffix will be "-yyyy-MM".

      Go here to find more information about java.text.SimpleDateFormat.

      Go here to see the DTD comment for the access-log tag.

4 Common Access Log Formats

    This section will describe common access log formats and how these are configured.

    This section involves the following formats:

    4.1 NCSA extended/combined access log format

      The NCSA extended/combined access log format looks like the following:


          "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
      Listing 6: NCSA extended/combined access log format

      Below is an implementation of the NCSA extended/combined access log format:


          <access-log
              ...
              format="$ip - $user [$time] &quot;$request&quot; $status $size &quot;$referer&quot; &quot;$agent&quot;"
              ...
          >
      Listing 7: access-log entry for NCSA extended/combined access log format

    4.2 Common Log Format (CLF)

      The Common Log Format (CLF) looks like the following:


          "%h %l %u %t \"%r\" %>s %b"
      Listing 8: The Common Log Format (CLF) log format

      Below is an implementation of the Common Log Format (CLF) log format:


          <access-log
              ...
              format="$ip - $user [$time] &quot;$request&quot; $status $size"
              ...
          >
      Listing 9: access-log entry for Common Log Format (CLF) log format

    4.3 Common Log Format with virtual host

      The Common Log Format with virtual host looks like the following:


          "%v %h %l %u %t \"%r\" %>s %b"
      Listing 10: Common Log Format (CLF) with virtual host log format

      Below is an implementation of the NCSA extended/combined access log format:


          <access-log
              ...
              format="$header:host  $ip - $user [$time] &quot;$request&quot; $status $size"
              ...
          >
      Listing 11: access-log entry for Common Log Format (CLF) with virual host log format

Copyright © 2005 IronFlare AB