Mercurial > hg > nginx-site

annotate xml/en/docs/debugging_log.xml @ 3090:27532d42102b default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the "rate" parameter of the "error_log" directive.
author Maxim Dounin <mdounin@mdounin.ru>
date Sun, 16 Jun 2024 06:55:30 +0300
parents 8a61d0ed67fa
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
580
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 516
diff changeset
1 <!--
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 516
diff changeset
2 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 516
diff changeset
3 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 516
diff changeset
4 -->
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 516
diff changeset
5
50
9d544687d02c Fixed DOCTYPE declaration.
Ruslan Ermilov <ru@nginx.com>
parents: 0
diff changeset
6 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7
123
7db449e89e92 Unified the use of the "name" attribute instead of "title".
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
8 <article name="A debugging log"
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9 link="/en/docs/debugging_log.html"
589
764fbac1b8b4 Added document revision.
Ruslan Ermilov <ru@nginx.com>
parents: 580
diff changeset
10 lang="en"
3051
8a61d0ed67fa Free nginx: no packages are provided for now.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2938
diff changeset
11 rev="7">
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
12
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 <section>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <para>
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
17 To enable a debugging log, nginx needs to be configured to support
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
18 debugging during the build:
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
19
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
21 ./configure --with-debug ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 213
diff changeset
24 Then the <literal>debug</literal> level should be set with the
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
25 <link doc="ngx_core_module.xml" id="error_log"/> directive:
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27 <programlisting>
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
28 error_log /path/to/log debug;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
29 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
30
1701
0108c6525d2a Added info about linux packages to "Debugging log".
Fedor Dikarev <fe@nginx.com>
parents: 1479
diff changeset
31 To verify that nginx is configured to support debugging,
0108c6525d2a Added info about linux packages to "Debugging log".
Fedor Dikarev <fe@nginx.com>
parents: 1479
diff changeset
32 run the <command>nginx -V</command> command:
0108c6525d2a Added info about linux packages to "Debugging log".
Fedor Dikarev <fe@nginx.com>
parents: 1479
diff changeset
33
0108c6525d2a Added info about linux packages to "Debugging log".
Fedor Dikarev <fe@nginx.com>
parents: 1479
diff changeset
34 <programlisting>
0108c6525d2a Added info about linux packages to "Debugging log".
Fedor Dikarev <fe@nginx.com>
parents: 1479
diff changeset
35 configure arguments: --with-debug ...
0108c6525d2a Added info about linux packages to "Debugging log".
Fedor Dikarev <fe@nginx.com>
parents: 1479
diff changeset
36 </programlisting>
0108c6525d2a Added info about linux packages to "Debugging log".
Fedor Dikarev <fe@nginx.com>
parents: 1479
diff changeset
37
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
38 The nginx binary version for Windows is always built with the debugging log
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 213
diff changeset
39 support, so only setting the <literal>debug</literal> level will suffice.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
40 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
41
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
42 <para>
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 213
diff changeset
43 Note that redefining the log without also specifying the
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 213
diff changeset
44 <literal>debug</literal>
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
45 level will disable the debugging log.
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
46 In the example below, redefining the log on the
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
47 <link doc="http/ngx_http_core_module.xml" id="server"/>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48 level disables the debugging log for this server:
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 <programlisting>
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
50 error_log /path/to/log debug;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52 http {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53 server {
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
54 error_log /path/to/log;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
55 ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
56 </programlisting>
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
57 To avoid this, either the line redefining the log should be
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 213
diff changeset
58 commented out, or the <literal>debug</literal> level specification should
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
59 also be added:
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 <programlisting>
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
61 error_log /path/to/log debug;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
63 http {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
64 server {
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
65 error_log /path/to/log debug;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
66 ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
68 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
69
1448
d3390895fe6e Added subchapter in the "Debugging log" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 589
diff changeset
70 </section>
d3390895fe6e Added subchapter in the "Debugging log" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 589
diff changeset
71
d3390895fe6e Added subchapter in the "Debugging log" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 589
diff changeset
72
d3390895fe6e Added subchapter in the "Debugging log" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 589
diff changeset
73 <section id="clients" name="Debugging log for selected clients">
d3390895fe6e Added subchapter in the "Debugging log" article.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 589
diff changeset
74
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75 <para>
516
8e1356bd281a Documented the "debug_connection" directive.
Ruslan Ermilov <ru@nginx.com>
parents: 271
diff changeset
76 It is also possible to enable the debugging log for
8e1356bd281a Documented the "debug_connection" directive.
Ruslan Ermilov <ru@nginx.com>
parents: 271
diff changeset
77 <link doc="ngx_core_module.xml" id="debug_connection">selected
8e1356bd281a Documented the "debug_connection" directive.
Ruslan Ermilov <ru@nginx.com>
parents: 271
diff changeset
78 client addresses</link> only:
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
79
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80 <programlisting>
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
81 error_log /path/to/log;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
83 events {
213
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
84 debug_connection 192.168.1.1;
5284967934df Improved markup and wording.
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
85 debug_connection 192.168.10.0/24;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
89
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
90 </section>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91
1449
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
92
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
93 <section id="memory" name="Logging to a cyclic memory buffer">
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
94
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
95 <para>
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
96 The debugging log can be written to a cyclic memory buffer:
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
97 <programlisting>
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
98 error_log memory:32m debug;
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
99 </programlisting>
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
100 Logging to the memory buffer on the <literal>debug</literal> level
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
101 does not have significant impact on performance even under high load.
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
102 In this case, the log can be extracted using
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
103 a <command>gdb</command> script like the following one:
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
104 <example>
1479
64ed0ce8ac5e Fixed the gdb script for dumping in-memory debug log.
Valentin Bartenev <vbart@nginx.com>
parents: 1449
diff changeset
105 set $log = ngx_cycle->log
1449
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
106
1479
64ed0ce8ac5e Fixed the gdb script for dumping in-memory debug log.
Valentin Bartenev <vbart@nginx.com>
parents: 1449
diff changeset
107 while $log->writer != ngx_log_memory_writer
64ed0ce8ac5e Fixed the gdb script for dumping in-memory debug log.
Valentin Bartenev <vbart@nginx.com>
parents: 1449
diff changeset
108 set $log = $log->next
1449
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
109 end
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
110
1479
64ed0ce8ac5e Fixed the gdb script for dumping in-memory debug log.
Valentin Bartenev <vbart@nginx.com>
parents: 1449
diff changeset
111 set $buf = (ngx_log_memory_buf_t *) $log->wdata
64ed0ce8ac5e Fixed the gdb script for dumping in-memory debug log.
Valentin Bartenev <vbart@nginx.com>
parents: 1449
diff changeset
112 dump binary memory debug_log.txt $buf->start $buf->end
1449
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
113 </example>
2938
b274d289798d Documented the use of cyclic memory buffer log with lldb.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1701
diff changeset
114 Or using an <command>lldb</command> script as follows:
b274d289798d Documented the use of cyclic memory buffer log with lldb.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1701
diff changeset
115 <example>
b274d289798d Documented the use of cyclic memory buffer log with lldb.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1701
diff changeset
116 expr ngx_log_t *$log = ngx_cycle->log
b274d289798d Documented the use of cyclic memory buffer log with lldb.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1701
diff changeset
117 expr while ($log->writer != ngx_log_memory_writer) { $log = $log->next; }
b274d289798d Documented the use of cyclic memory buffer log with lldb.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1701
diff changeset
118 expr ngx_log_memory_buf_t *$buf = (ngx_log_memory_buf_t *) $log->wdata
b274d289798d Documented the use of cyclic memory buffer log with lldb.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1701
diff changeset
119 memory read --force --outfile debug_log.txt --binary $buf->start $buf->end
b274d289798d Documented the use of cyclic memory buffer log with lldb.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1701
diff changeset
120 </example>
1449
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
121 </para>
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
122
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
123 </section>
c79501e16e26 Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1448
diff changeset
124
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
125 </article>