Mercurial > hg > nginx-site
annotate xml/en/docs/debugging_log.xml @ 2090:a9a9a052b5bd
Documented the "CAP_NET_RAW" capability for transparent proxying.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 26 Dec 2017 15:28:53 +0300 |
parents | 0108c6525d2a |
children | b274d289798d |
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 | 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 | 10 lang="en" |
1701
0108c6525d2a
Added info about linux packages to "Debugging log".
Fedor Dikarev <fe@nginx.com>
parents:
1479
diff
changeset
|
11 rev="5"> |
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 | 17 To enable a debugging log, nginx needs to be configured to support |
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 | 24 Then the <literal>debug</literal> level should be set with the |
213 | 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 | 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 | 49 The nginx binary version for Windows is always built with the debugging log |
271 | 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 | 54 Note that redefining the log without also specifying the |
55 <literal>debug</literal> | |
213 | 56 level will disable the debugging log. |
57 In the example below, redefining the log on the | |
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 | 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 | 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 | 68 To avoid this, either the line redefining the log should be |
271 | 69 commented out, or the <literal>debug</literal> level specification should |
213 | 70 also be added: |
0
61e04fc01027
Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff
changeset
|
71 <programlisting> |
213 | 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 | 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 | 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 | 95 debug_connection 192.168.1.1; |
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> |
c79501e16e26
Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1448
diff
changeset
|
125 </para> |
c79501e16e26
Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1448
diff
changeset
|
126 |
c79501e16e26
Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1448
diff
changeset
|
127 </section> |
c79501e16e26
Documented cyclic memory buffer support for error_log.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1448
diff
changeset
|
128 |
0
61e04fc01027
Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff
changeset
|
129 </article> |