Access logging

Where to find access logs, how to configure them and how to configure access log rotation
You're viewing a development version of router, the latest released version is 1.24.0
Go to the latest released version

The Director writes two access logs:

  • The access log, /var/log/acd-router/access.log, has one entry for every client request.
  • The access error log, /var/log/acd-router/access-error.log, has one entry for every failed request, that is, those with status code 400 or higher. By default, each entry includes the selection trace, that is, the routing rules that were evaluated for the request, which helps with troubleshooting.

Configuration

Both logs are configured under services.routing.settings.logging, in the accessLog and accessErrorLog objects. Both objects have these settings:

  • enable turns the log on or off. The access log is enabled by default, and the access error log is disabled by default.
  • format is either:
    • combined, the default, for the Apache Combined Log Format. In the access error log, the selection trace is added at the end of each entry, within brackets.
    • custom, for the format given by customFormat.
  • customFormat is the log format used when format is custom. See Custom Format Syntax. The default gives practically the same output as the combined format, so it can be used as a starting point. See Differences From the Combined Format for the exceptions. The defaults are:
    • Access log: %h %l %u %t "%r" %>s %B "%{Referer}i" "%{User-Agent}i"
    • Access error log: %h %l %u %t "%r" %>s %B "%{Referer}i" "%{User-Agent}i" [%{trace}x]

Selection Trace Depth

The selection trace lists the routing rules that were evaluated for a request and how they ended. It is only included for requests that were rejected by the routing.

accessErrorLog.depth is the number of steps of the selection trace that are logged, counted from the end. It is 3 by default and must be at least 1. The depth also applies to the access log, if its custom format includes the %{trace}x specifier.

Custom Format Syntax

A custom format uses the syntax of the Apache LogFormat directive, but only the following specifiers are supported:

SpecifierValue
%%A literal %.
%bThe size of the response body in bytes, - if it is empty.
%BThe size of the response body in bytes.
%DThe time taken to handle the request, in microseconds.
%hThe client IP address.
%{Header}iThe value of the request header Header, - if there is none. If the header occurs more than once, only the last value is logged.
%lThe client’s identity from identd. It is never known, so it is always -.
%rThe request line, for example GET /index.m3u8 HTTP/1.1.
%s, %>sThe response status code.
%tThe time the request was received, within brackets, for example [05/Nov/2026:10:00:00 +0000].
%{format}tThe time the request was received, without brackets. format is a strftime format string. For example, %{%Y-%m-%dT%H:%M:%S}t.
%TThe time taken to handle the request, in seconds.
%{unit}TThe time taken to handle the request, in s, ms or us.
%uThe authenticated user. It is never known, so it is always -.
%{trace}xThe selection trace, without brackets. It is empty for requests that were not rejected by the routing.

The times in %t and %{format}t, and in the combined format, are in UTC. The times in %D, %T and %{unit}T are rounded down, so for example 1056 microseconds is logged as 1 by %{ms}T.

Other text is written as it is. Double quotes can be written directly, or escaped as \". \\, \n and \t are also recognized.

In the values of %r and %{Header}i, characters are escaped as Apache does:

  • " and \ are escaped with a backslash.
  • Tabs are written as \t.
  • Other characters that are not printable ASCII are written as hexadecimal escape sequences. For example, é is written as \xc3\xa9.

A mistake in a custom format does not make the configuration fail. Instead, specifiers that are not recognized, such as %Z, %{msec}t or a %{ without a closing }, are written to the log as they are, and a warning is written to the Director’s log when the configuration is applied. Check the log entries after changing the format.

Differences From the Combined Format

The default values of customFormat give the same output as the combined format, except in these cases:

  • If a request has no User-Agent header, the combined format logs it as "", while the custom format logs it as "-".
  • If the Referer header contains a comma, the combined format only logs the part before the first comma, while the custom format logs the whole value.
  • Characters that are not printable ASCII in the request line or in the Referer and User-Agent headers are written as they are by the combined format, while the custom format writes them as escape sequences. For example, é is written as é by the combined format and as \xc3\xa9 by the custom format.

Examples

Access Log

To enable the access log and use the combined format, run:

$ confcli services.routing.settings.logging.accessLog.enable true
$ confcli services.routing.settings.logging.accessLog.format combined

The access log then gets entries such as:

::1 - - [29/May/2023:07:20:00 +0000] "GET /vod/batman.m3u8 HTTP/1.1" 302 0 "-" "curl/7.61.1"

To log the client IP address, the request line, the status code, the response time in milliseconds and the X-Device-ID request header, run:

$ confcli services.routing.settings.logging.accessLog.customFormat '%h "%r" %>s %{ms}T "%{X-Device-ID}i"'
$ confcli services.routing.settings.logging.accessLog.format custom

The access log then gets entries such as:

::1 "GET /vod/batman.m3u8 HTTP/1.1" 302 2 "device-1234"

Access Error Log

To enable the access error log and use the combined format, run:

$ confcli services.routing.settings.logging.accessErrorLog.enable true
$ confcli services.routing.settings.logging.accessErrorLog.format combined

The access error log then gets entries such as the following, with the selection trace at the end:

::1 - - [14/Jul/2023:12:42:42 +0000] "GET /private/batman.m3u8 HTTP/1.1" 403 0 "-" "...  Safari/605.1.15" [verify_token.0.randis, verify_token.1.rejected]

To log the time in ISO 8601 format, the client IP address, the request line, the status code and the selection trace, run:

$ confcli services.routing.settings.logging.accessErrorLog.customFormat '%{%Y-%m-%dT%H:%M:%S%z}t %h "%r" %>s [%{trace}x]'
$ confcli services.routing.settings.logging.accessErrorLog.format custom

The access error log then gets entries such as:

2023-07-14T12:42:42+0000 ::1 "GET /private/batman.m3u8 HTTP/1.1" 403 [verify_token.0.randis, verify_token.1.rejected]

Access Log Rotation

The access logs are rotated and compressed once the file reaches a size of 100 MB. By default, 10 rotated logs are stored before being rotated out. These rotation parameters can be reconfigured by editing the lines

size 100M
rotate 10

in /etc/logrotate.d/acd-router-access-log. For more log rotation configuration possibilities, refer to the Logrotate documentation.