== link:index.html[Index] -> link:modules.html[Modules] -> link:modules_loggers.html[Loggers]

Logger: Custom
~~~~~~~~~~~~~~

This module implements a flexible mechanism for logging requests made
to the server, using a user-specified format.

The format in which the request will be logged is defined by a string.
This string is used to log each request to the log. It can contain
both literal characters and a set of variables. All the literal
characters will be copied to the log. The following variables will be
evaluated right before writing each log entry:

[cols="10%,40%,50%",options="header"]
|===================================================================================
|Variable                |Example                    |Description
|`${ip_remote}`          |74.125.67.100              |Remote IP-address
|`${ip_local}`           |10.0.0.1                   |Local IP-address
|`${port_server}`        |80                         |Port of the server serving the request
|`${protocol}`           |http                       |Request Protocol
|`${query_string}`       |?bar=foo                   |The query string, if exists
|`${request}`            |/file.txt                  |URL path requested
|`${request_first_line}` |GET / HTTP/1.0             |First line of HTTP request
|`${request_original}`   |/file.txt                  |URL path requested before any rewrite
|`${response_size}`      |1234                       |Size of the response in bytes
|`${status}`             |200                        |Response status code
|`${now}`                |08/Apr/2009:12:02:11 +0200 |Time: in common log format time format
|`${time_secs}`          |1239185281                 |Time: seconds since Epoch
|`${time_msecs}`         |18446744071655350332       |Time: milliseconds since Epoch
|`${transport}`          |https                      |Transport type: `http` or `https`
|`${user_remote}`        |guest                      |Remote user (authentication)
|`${vserver_name}`       |default                    |Virtual Server nick name
|`${vserver_name_req}`   |example.com                |Requested host (Host: header), or vserver nickname if absent
|`${http_host}`          |example.com                |"Host:" header of the request
|`${http_referrer}`      |example.com/page           |"Referrer:" header of the request
|`${http_user_agent}`    |Mozilla/1.0.0              |"User-Agent:" header of the request
|`${http_cokkie}`        |key=val                    |"Cookie:" header of the request
|===================================================================================

The templating subsystem provides slicing support in pretty much the
same way that the Python strings do, allowing to use specific portions
of any of these substitution macros. You can read more about this on
the link:other_goodies.html#templating[Template Subsystem] section of
the documentation.

[[examples]]
Example
~~~~~~~

For instance, the following format string:

----
[${now}] ${ip_remote}: ${request} (${status})
----

would generate this entry in the log:

----
[08/Apr/2009:12:02:11 +0200] 74.125.67.100: /file.txt (200)
----


Apache's comined format
~~~~~~~~~~~~~~~~~~~~~~~
The following formats are all like Apache's combined format, except the second field not being the client ident but the (way more interesting) HTTP host or vserver name.

* Virtual server name
+
----
${ip_remote} ${vserver_name} ${user_remote} [${now}] "${request_first_line}" ${status} ${response_size} "${http_referrer}" "${http_user_agent}"
----

* Host
+
----
${ip_remote} ${http_host} ${user_remote} [${now}] "${request_first_line}" ${status} ${response_size} "${http_referrer}" "${http_user_agent}"
----

* Host if present, otherwise virtual serven name
+
----
${ip_remote} ${vserver_name_req} ${user_remote} [${now}] "${request_first_line}" ${status} ${response_size} "${http_referrer}" "${http_user_agent}"
----