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.

Overview

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:

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

As of version 24.9, this is the default and does not need to be specified in application.properties. HTTP access logging is enabled by default as well. You may adjust as needed.

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, per RFC 1945.
  • %{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 "-"
  • %{X-Forwarded-For}i = The value of the X-Forwarded-For HTTP request header, if present. This will be the IP address of the originating client when Tomcat is running behind by a proxy or load balancer.
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

Set Format in application.properties

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

server.tomcat.basedir=.
server.tomcat.accesslog.enabled=true
server.tomcat.accesslog.directory=logs
server.tomcat.accesslog.pattern=%h %l %u %t "%r" %s %b %D %S %I "%{Referer}i" "%{User-Agent}i" %{LABKEY.username}s %{X-Forwarded-For}i

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?
dataRegionName=query&query.queryName=things&schemaName=helloworld&query.color%2Fname~eq=Red&quer
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" username@labkey.com

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 should first confirm that your load balancer is configured to preserve source IPs:

The recommended pattern above includes both:
  • %h = The IP address of the ALB/ELB/proxy
  • %{X-Forwarded-For}i = The actual source IP address

Output JSON-formatted HTTP access log

If you would like to output the equivalent log in JSON format to stdout (such as for consumption by another tool), you can use these properties, included in the development version of the application.properties template. Uncomment rows to use at least the enabled property; the pattern format can also be controlled here.

## https://tomcat.apache.org/tomcat-9.0-doc/config/valve.html#JSON_Access_Log_Valve
#jsonaccesslog.enabled=true

## Optional configuration, modeled on the non-JSON Spring Boot properties
## https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#application-properties.server.server.tomcat.accesslog.buffered
#jsonaccesslog.pattern=%h %t %m %U %s %b %D %S "%{Referer}i" "%{User-Agent}i" %{LABKEY.username}s %{X-Forwarded-For}i
#jsonaccesslog.condition-if=attributeName
#jsonaccesslog.condition-unless=attributeName

Related Topics

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand allcollapse all