Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_session_log_module.xml @ 2593:eeed494bba51

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Unified phrases about configuration levels and inheritance.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 21 Sep 2020 15:45:07 +0300
parents ca7568f67dee
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
3 <!--
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
4 Copyright (C) Nginx, Inc.
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
5 -->
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
6
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9 <module name="Module ngx_http_session_log_module"
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 link="/en/docs/http/ngx_http_session_log_module.html"
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 lang="en"
2593
eeed494bba51 Unified phrases about configuration levels and inheritance.
Ruslan Ermilov <ru@nginx.com>
parents: 2142
diff changeset
12 rev="3">
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 <section id="summary">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
17 The <literal>ngx_http_session_log_module</literal> module enables logging
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
18 sessions (that is, aggregates of multiple HTTP requests) instead of
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
19 individual HTTP requests.
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
21
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23 <note>
1128
1594ed379f1f De-i18n'ed <commercial_version/>.
Ruslan Ermilov <ru@nginx.com>
parents: 1088
diff changeset
24 This module is available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>.
Ruslan Ermilov <ru@nginx.com>
parents: 1088
diff changeset
25 <commercial_version>commercial subscription</commercial_version>.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26 </note>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
28
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
29 </section>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
30
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
31
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32 <section id="example" name="Example Configuration">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
33
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
34 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
35 The following configuration sets up a session log and maps requests to
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
36 sessions according to the request client address and <header>User-Agent</header>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
37 request header field:
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
38 <example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
39 session_log_zone /path/to/log format=combined
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
40 zone=one:1m timeout=30s
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
41 md5=$binary_remote_addr$http_user_agent;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
42
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
43 location /media/ {
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
44 session_log one;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
45 }
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
46 </example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 </section>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52 <section id="directives" name="Directives">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53
2142
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
54 <directive name="session_log">
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
55 <syntax><value>name</value> | <literal>off</literal></syntax>
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
56 <default>off</default>
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
57 <context>http</context>
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
58 <context>server</context>
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
59 <context>location</context>
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
60
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
61 <para>
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
62 Enables the use of the specified session log.
2593
eeed494bba51 Unified phrases about configuration levels and inheritance.
Ruslan Ermilov <ru@nginx.com>
parents: 2142
diff changeset
63 The special value <literal>off</literal> cancels the effect
eeed494bba51 Unified phrases about configuration levels and inheritance.
Ruslan Ermilov <ru@nginx.com>
parents: 2142
diff changeset
64 of the <literal>session_log</literal> directives
eeed494bba51 Unified phrases about configuration levels and inheritance.
Ruslan Ermilov <ru@nginx.com>
parents: 2142
diff changeset
65 inherited from the previous configuration level.
2142
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
66 </para>
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
67
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
68 </directive>
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
69
ca7568f67dee Sorted directives alphabetically.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
70
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
71 <directive name="session_log_format">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
72 <syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 <value>name</value>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
74 <value>string</value> ...</syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75 <default>combined "..."</default>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 <context>http</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
78 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
79 Specifies the output format of a log.
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
80 The value of the <var>$body_bytes_sent</var> variable is aggregated across
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
81 all requests in a session.
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
82 The values of all other variables available for logging correspond to the
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
83 first request in a session.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 </directive>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
89 <directive name="session_log_zone">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
90 <syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91 <value>path</value>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
92 <literal>zone</literal>=<value>name</value>:<value>size</value>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
93 [<literal>format</literal>=<value>format</value>]
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
94 [<literal>timeout</literal>=<value>time</value>]
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
95 [<literal>id</literal>=<value>id</value>]
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
96 [<literal>md5</literal>=<value>md5</value>]
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
97 </syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
98 <default/>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
99 <context>http</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
100
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
101 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
102 Sets the path to a log file and configures the shared memory zone that is used
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
103 to store currently active sessions.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
104 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
105
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
106 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
107 A session is considered active for as long as the time elapsed since
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
108 the last request in the session does not exceed the specified
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
109 <literal>timeout</literal> (by default, 30 seconds).
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
110 Once a session is no longer active, it is written to the log.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
111 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
112
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
113 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
114 The <literal>id</literal> parameter identifies the
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
115 session to which a request is mapped.
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
116 The <literal>id</literal> parameter is set to the hexadecimal representation
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
117 of an MD5 hash (for example, obtained from a cookie using variables).
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
118 If this parameter is not specified or does not represent the valid
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
119 MD5 hash, nginx computes the MD5 hash from the value of
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
120 the <literal>md5</literal> parameter and creates a new session using this hash.
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
121 Both the <literal>id</literal> and <literal>md5</literal> parameters
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
122 can contain variables.
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
123 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
124
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
125 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
126 The <literal>format</literal> parameter sets the custom session log
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
127 format configured by the <link id="session_log_format"/> directive.
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
128 If <literal>format</literal> is not specified, the predefined
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
129 “<literal>combined</literal>” format is used.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
130 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132 </directive>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
134 </section>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
135
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
136
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
137 <section id="variables" name="Embedded Variables">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
138
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
139 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
140 The <literal>ngx_http_session_log_module</literal> module supports
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141 two embedded variables:
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
143 <list type="tag">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
144
1155
07402a11fd8d Assigned IDs to tags describing variables.
Vladimir Homutov <vl@nginx.com>
parents: 1128
diff changeset
145 <tag-name id="var_session_log_id"><var>$session_log_id</var></tag-name>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 <tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147 current session ID;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
148 </tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
149
1155
07402a11fd8d Assigned IDs to tags describing variables.
Vladimir Homutov <vl@nginx.com>
parents: 1128
diff changeset
150 <tag-name id="var_session_log_binary_id"><var>$session_log_binary_id</var>
07402a11fd8d Assigned IDs to tags describing variables.
Vladimir Homutov <vl@nginx.com>
parents: 1128
diff changeset
151 </tag-name>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
152 <tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
153 current session ID in binary form (16 bytes).
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
154 </tag-desc>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
155
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
156 </list>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
157 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
158
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
159 </section>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161 </module>