LabKey Server can log each HTTP request sent to the server, including requests from logged in users, anonymous guest users, and API calls into the server. This access_log can be customized if needed following the guidance in this topic.


Information is written to a text file on the file system using Tomcat's native access logging. Access logs can include details such as queries requested, user information, server actions invoked, etc.

  • Located in the <LABKEY_HOME>/logs directory (or in a "logs" directory under the "build" node of a development machine).
  • The file name includes the date: access_log.YYYY-MM-DD.txt
  • This log is rotated daily at midnight

Recommended LabKey Server Access Log Format

For production installations of the LabKey server, we recommend the following format, included in the template with your distribution.

%h %l %u %t "%r" %s %b %D %S "%{Referer}i" "%{User-Agent}i" %{LABKEY.username}s

This format uses the following elements:

  • %D = The time taken by the server to process the request. This is valuable when debugging performance problems.
  • %S = Tomcat user session ID
  • %{Referer}i = Referring URL - Note that the misspelling of "Referer" is intentional.
  • %{User-Agent}I = The name of the client program used to make the HTTP request.
  • %{LABKEY.username}s = The username of the person accessing the LabKey server. If the person is not logged in, then this will be a "-"
Also consider 3 other LabKey specific fields that might be of interest in particular circumstances:
  • %{LABKEY.container}r = The LabKey server container being accessed during the request
  • %{LABKEY.controller}r = The LabKey server controller being used during the request
  • %{LABKEY.action}r = The LabKey server action being used during the request

Enable and Set Format in

The information written to the log, and its format, is controlled by the "Enable Tomcat Access Log" section in the <LABKEY_HOME>/config/ file. These defaults use the pattern shown above, and set the location for writing the logs to "logs" under <LABKEY_HOME>:

## Enable tomcat access log
server.tomcat.accesslog.pattern=%h %l %u %t "%r" %s %b %D %S %I "%{Referrer}i" "%{User-Agent}i" %{LABKEY.username}s

This configuration provides log entries like the following:

0:0:0:0:0:0:0:1 - - [03/Aug/2020:10:11:16 -0700] "GET /labkey/HiWorld/query-getQuery.api?
y.columns=name&apiVersion=9.1 HTTP/1.1" 200 2714 186 D9003A0B7132A3F98D1E63E613859230 "-"
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/84.0.4147.89 Safari/537.36"

Pattern Code Description

Reference information below was taken from the Tomcat docs

  • %a - Remote IP address
  • %A - Local IP address
  • %b - Bytes sent, excluding HTTP headers, or ‘-’ if zero
  • %B - Bytes sent, excluding HTTP headers
  • %h - Remote host name (or IP address if resolveHosts is false)
  • %H - Request protocol
  • %l - Remote logical username from identd (always returns ‘-‘)
  • %m - Request method (GET, POST, etc.)
  • %p - Local port on which this request was received
  • %q - Query string (prepended with a ‘?’ if it exists)
  • %r - First line of the request (method and request URI)
  • %s - HTTP status code of the response
  • %S - User session ID
  • %t - Date and time, in Common Log Format
  • %u - Remote user that was authenticated (if any), else ‘-‘
  • %U - Requested URL path
  • %v - Local server name
  • %D - Time taken to process the request, in millis. Note that in httpd %D is microseconds.
  • %T - Time taken to process the request, in seconds
  • %I - current request thread name (can compare later with stacktraces)
There is also support to write information from the cookie, incoming header, outgoing response headers, the Session or something else in the ServletRequest. It is modeled after the Apache syntax:
  • %{xxx}i for incoming request headers
  • %{xxx}o for outgoing response headers
  • %{xxx}c for a specific request cookie
  • %{xxx}r xxx is an attribute in the ServletRequest
  • %{xxx}s xxx is an attribute in the HttpSession

Obtaining Source IP Address When Using a Load Balancer

When using a load balancer, such as AWS ELB or ALB, you may notice that your logs are capturing the IP address of the load balancer itself, rather than the user's originating IP address. To obtain the source IP address, first confirm that your load balancer is configured to preserve source IPs:

One possible valve configuration pattern to use is:
pattern="%{org.apache.catalina.AccessLog.RemoteAddr}r %l %u %t "%r" %s %b %D %S "%{Referer}i" "%{User-Agent}i" %{LABKEY.username}s %q"

Output JSON-formatted HTTP access log

If you would like to output the equivalent log but in JSON format (such as for consumption by another tool), you can use these properties, included in the development version of the template. Note that the pattern format can also be controlled here. Remember to remove the # to uncomment properties you'd like to use:


## Optional configuration, modeled on the non-JSON Spring Boot properties
#jsonaccesslog.pattern=%h %t %m %U %s %b %D %S "%{Referer}i" "%{User-Agent}i" %{LABKEY.username}s

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all