Access logging
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:
enableturns the log on or off. The access log is enabled by default, and the access error log is disabled by default.formatis 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 bycustomFormat.
customFormatis the log format used whenformatiscustom. See Custom Format Syntax. The default gives practically the same output as thecombinedformat, 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]
- Access log:
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:
| Specifier | Value |
|---|---|
%% | A literal %. |
%b | The size of the response body in bytes, - if it is empty. |
%B | The size of the response body in bytes. |
%D | The time taken to handle the request, in microseconds. |
%h | The client IP address. |
%{Header}i | The value of the request header Header, - if there is none. If the header occurs more than once, only the last value is logged. |
%l | The client’s identity from identd. It is never known, so it is always -. |
%r | The request line, for example GET /index.m3u8 HTTP/1.1. |
%s, %>s | The response status code. |
%t | The time the request was received, within brackets, for example [05/Nov/2026:10:00:00 +0000]. |
%{format}t | The time the request was received, without brackets. format is a strftime format string. For example, %{%Y-%m-%dT%H:%M:%S}t. |
%T | The time taken to handle the request, in seconds. |
%{unit}T | The time taken to handle the request, in s, ms or us. |
%u | The authenticated user. It is never known, so it is always -. |
%{trace}x | The 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-Agentheader, thecombinedformat logs it as"", while the custom format logs it as"-". - If the
Refererheader contains a comma, thecombinedformat 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
RefererandUser-Agentheaders are written as they are by thecombinedformat, while the custom format writes them as escape sequences. For example,éis written aséby thecombinedformat and as\xc3\xa9by 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.