debugging_log.xml

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

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

<article name="A debugging log"
         link="/en/docs/debugging_log.html"
         lang="en"
         rev="6">


<section>

<para>
To enable a debugging log, nginx needs to be configured to support
debugging during the build:

<programlisting>
./configure --with-debug ...
</programlisting>

Then the <literal>debug</literal> level should be set with the
<link doc="ngx_core_module.xml" id="error_log"/> directive:

<programlisting>
error_log /path/to/log debug;
</programlisting>

To verify that nginx is configured to support debugging,
run the <command>nginx -V</command> command:

<programlisting>
configure arguments: --with-debug ...
</programlisting>

Pre-built <link doc="../linux_packages.xml">Linux</link> packages
provide out-of-the-box support for debugging log with
the <literal>nginx-debug</literal> binary (1.9.8)
which can be run using commands

<programlisting>
service nginx stop
service nginx-debug start
</programlisting>

and then set the <literal>debug</literal> level.
The nginx binary version for Windows is always built with the debugging log
support, so only setting the <literal>debug</literal> level will suffice.
</para>

<para>
Note that redefining the log without also specifying the
<literal>debug</literal>
level will disable the debugging log.
In the example below, redefining the log on the
<link doc="http/ngx_http_core_module.xml" id="server"/>
level disables the debugging log for this server:
<programlisting>
error_log /path/to/log debug;

http {
    server {
        error_log /path/to/log;
        ...
</programlisting>
To avoid this, either the line redefining the log should be
commented out, or the <literal>debug</literal> level specification should
also be added:
<programlisting>
error_log /path/to/log debug;

http {
    server {
        error_log /path/to/log debug;
        ...
</programlisting>
</para>

</section>


<section id="clients" name="Debugging log for selected clients">

<para>
It is also possible to enable the debugging log for
<link doc="ngx_core_module.xml" id="debug_connection">selected
client addresses</link> only:

<programlisting>
error_log /path/to/log;

events {
    debug_connection 192.168.1.1;
    debug_connection 192.168.10.0/24;
}
</programlisting>
</para>

</section>


<section id="memory" name="Logging to a cyclic memory buffer">

<para>
The debugging log can be written to a cyclic memory buffer:
<programlisting>
error_log memory:32m debug;
</programlisting>
Logging to the memory buffer on the <literal>debug</literal> level
does not have significant impact on performance even under high load.
In this case, the log can be extracted using
a <command>gdb</command> script like the following one:
<example>
set $log = ngx_cycle->log

while $log->writer != ngx_log_memory_writer
    set $log = $log->next
end

set $buf = (ngx_log_memory_buf_t *) $log->wdata
dump binary memory debug_log.txt $buf->start $buf->end
</example>
Or using an <command>lldb</command> script as follows:
<example>
expr ngx_log_t *$log = ngx_cycle->log
expr while ($log->writer != ngx_log_memory_writer) { $log = $log->next; }
expr ngx_log_memory_buf_t *$buf = (ngx_log_memory_buf_t *) $log->wdata
memory read --force --outfile debug_log.txt --binary $buf->start $buf->end
</example>
</para>

</section>

</article>