<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_session_log_module"
        link="/en/docs/http/ngx_http_session_log_module.html"
        lang="en"
        rev="2">

<section id="summary">

<para>
The <literal>ngx_http_session_log_module</literal> module enables logging
sessions (that is, aggregates of multiple HTTP requests) instead of
individual HTTP requests.
</para>

<para>
<note>
This module is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Example Configuration">

<para>
The following configuration sets up a session log and maps requests to
sessions according to the request client address and <header>User-Agent</header>
request header field:
<example>
    session_log_zone /path/to/log format=combined
                     zone=one:1m timeout=30s
                     md5=$binary_remote_addr$http_user_agent;

    location /media/ {
        session_log one;
    }
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="session_log_format">
<syntax>
    <value>name</value>
    <value>string</value> ...</syntax>
<default>combined "..."</default>
<context>http</context>

<para>
Specifies the output format of a log.
The value of the <var>$body_bytes_sent</var> variable is aggregated across
all requests in a session.
The values of all other variables available for logging correspond to the
first request in a session.
</para>

</directive>


<directive name="session_log_zone">
<syntax>
    <value>path</value>
    <literal>zone</literal>=<value>name</value>:<value>size</value>
    [<literal>format</literal>=<value>format</value>]
    [<literal>timeout</literal>=<value>time</value>]
    [<literal>id</literal>=<value>id</value>]
    [<literal>md5</literal>=<value>md5</value>]
</syntax>
<default/>
<context>http</context>

<para>
Sets the path to a log file and configures the shared memory zone that is used
to store currently active sessions.
</para>

<para>
A session is considered active for as long as the time elapsed since
the last request in the session does not exceed the specified
<literal>timeout</literal> (by default, 30 seconds).
Once a session is no longer active, it is written to the log.
</para>

<para>
The <literal>id</literal> parameter identifies the
session to which a request is mapped.
The <literal>id</literal> parameter is set to the hexadecimal representation
of an MD5 hash (for example, obtained from a cookie using variables).
If this parameter is not specified or does not represent the valid
MD5 hash, nginx computes the MD5 hash from the value of
the <literal>md5</literal> parameter and creates a new session using this hash.
Both the <literal>id</literal> and <literal>md5</literal> parameters
can contain variables.
</para>

<para>
The <literal>format</literal> parameter sets the custom session log
format configured by the <link id="session_log_format"/> directive.
If <literal>format</literal> is not specified, the predefined
“<literal>combined</literal>” format is used.
</para>

</directive>


<directive name="session_log">
<syntax><value>name</value> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Enables the use of the specified session log.
The special value <literal>off</literal> cancels all
<literal>session_log</literal> directives inherited from the previous
configuration level.
</para>

</directive>

</section>


<section id="variables" name="Embedded Variables">

<para>
The <literal>ngx_http_session_log_module</literal> module supports
two embedded variables:

<list type="tag">

<tag-name id="var_session_log_id"><var>$session_log_id</var></tag-name>
<tag-desc>
current session ID;
</tag-desc>

<tag-name id="var_session_log_binary_id"><var>$session_log_binary_id</var>
</tag-name>
<tag-desc>
current session ID in binary form (16 bytes).
</tag-desc>

</list>
</para>

</section>

</module>