nginx-site: xml/en/docs/debugging

annotate xml/en/docs/debugging_log.xml @ 3011:55d49eb065ac

Fixed example in the js_periodic directive.

author	Yaroslav Zhuravlev <yar@nginx.com>
date	Thu, 14 Sep 2023 16:38:00 +0100
parents	b274d289798d
children	8a61d0ed67fa

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"
2938 b274d289798d Documented the use of cyclic memory buffer log with lldb. Sergey Kandaurov <pluknet@nginx.com> parents: 1701 diff changeset	11 rev="6">
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
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	38 Pre-built <link doc="../linux_packages.xml">Linux</link> packages
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	39 provide out-of-the-box support for debugging log with
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	40 the <literal>nginx-debug</literal> binary (1.9.8)
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	41 which can be run using commands
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	42
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	43 <programlisting>
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	44 service nginx stop
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	45 service nginx-debug start
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	46 </programlisting>
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	47
0108c6525d2a Added info about linux packages to "Debugging log". Fedor Dikarev <fe@nginx.com> parents: 1479 diff changeset	48 and then set the <literal>debug</literal> level.
213 5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	49 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	50 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	51 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	52
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	53 <para>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 213 diff changeset	54 Note that redefining the log without also specifying the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 213 diff changeset	55 <literal>debug</literal>
213 5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	56 level will disable the debugging log.
5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	57 In the example below, redefining the log on the
5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	58 <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	59 level disables the debugging log for this server:
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;
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>
213 5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	68 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	69 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	70 also be added:
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	71 <programlisting>
213 5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	72 error_log /path/to/log debug;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	73
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	74 http {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	75 server {
213 5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	76 error_log /path/to/log debug;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	77 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	78 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	79 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	80
1448 d3390895fe6e Added subchapter in the "Debugging log" article. Yaroslav Zhuravlev <yar@nginx.com> parents: 589 diff changeset	81 </section>
d3390895fe6e Added subchapter in the "Debugging log" article. Yaroslav Zhuravlev <yar@nginx.com> parents: 589 diff changeset	82
d3390895fe6e Added subchapter in the "Debugging log" article. Yaroslav Zhuravlev <yar@nginx.com> parents: 589 diff changeset	83
d3390895fe6e Added subchapter in the "Debugging log" article. Yaroslav Zhuravlev <yar@nginx.com> parents: 589 diff changeset	84 <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	85
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	86 <para>
516 8e1356bd281a Documented the "debug_connection" directive. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	87 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	88 <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	89 client addresses</link> only:
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	90
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	91 <programlisting>
213 5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	92 error_log /path/to/log;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	93
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	94 events {
213 5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	95 debug_connection 192.168.1.1;
5284967934df Improved markup and wording. Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	96 debug_connection 192.168.10.0/24;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	97 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	98 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	99 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	100
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	101 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	102
1449 c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	103
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	104 <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	105
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	106 <para>
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	107 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	108 <programlisting>
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	109 error_log memory:32m debug;
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	110 </programlisting>
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	111 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	112 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	113 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	114 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	115 <example>
1479 64ed0ce8ac5e Fixed the gdb script for dumping in-memory debug log. Valentin Bartenev <vbart@nginx.com> parents: 1449 diff changeset	116 set $log = ngx_cycle->log
1449 c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	117
1479 64ed0ce8ac5e Fixed the gdb script for dumping in-memory debug log. Valentin Bartenev <vbart@nginx.com> parents: 1449 diff changeset	118 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	119 set $log = $log->next
1449 c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	120 end
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	121
1479 64ed0ce8ac5e Fixed the gdb script for dumping in-memory debug log. Valentin Bartenev <vbart@nginx.com> parents: 1449 diff changeset	122 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	123 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	124 </example>
2938 b274d289798d Documented the use of cyclic memory buffer log with lldb. Sergey Kandaurov <pluknet@nginx.com> parents: 1701 diff changeset	125 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	126 <example>
b274d289798d Documented the use of cyclic memory buffer log with lldb. Sergey Kandaurov <pluknet@nginx.com> parents: 1701 diff changeset	127 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	128 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	129 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	130 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	131 </example>
1449 c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	132 </para>
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	133
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	134 </section>
c79501e16e26 Documented cyclic memory buffer support for error_log. Yaroslav Zhuravlev <yar@nginx.com> parents: 1448 diff changeset	135
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	136 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/debugging_log.xml @ 3011:55d49eb065ac