nginx-log

Posted on Edited on In ,

Logging

nginx provides two kinds of logs, ‘error’ log and debug log, you can use several APIs(macro) to log info to console or file, let’s explain how to use these APIs in detail.

support formats

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/* src/core/ngx_string.c
 * supported formats:
 *    %[0][width][x][X]O        off_t
 *    %[0][width]T              time_t
 *    %[0][width][u][x|X]z      ssize_t/size_t
 *    %[0][width][u][x|X]d      int/u_int
 *    %[0][width][u][x|X]l      long
 *    %[0][width|m][u][x|X]i    ngx_int_t/ngx_uint_t
 *    %[0][width][u][x|X]D      int32_t/uint32_t
 *    %[0][width][u][x|X]L      int64_t/uint64_t
 *    %[0][width|m][u][x|X]A    ngx_atomic_int_t/ngx_atomic_uint_t
 *    %[0][width][.width]f      double, max valid number fits to %18.15f
 *    %P                        ngx_pid_t
 *    %M                        ngx_msec_t
 *    %r                        rlim_t
 *    %p                        void *
 *    %V                        ngx_str_t *
 *    %v                        ngx_variable_value_t *
 *    %s                        null-terminated string
 *    %*s                       length and string
 *    %Z                        '\0'
 *    %N                        '\n'
 *    %c                        char
 *    %%                        %
 *
 *  reserved:
 *    %t                        ptrdiff_t
 *    %S                        null-terminated wchar string
 *    %C                        wchar
 */

usage

user can configure log level like this

1
error /tmp/log debug;

level can be:

  • emerg
  • alert
  • crit
  • error
  • warn
  • notice
  • info
  • debug -> debug all

specific debug component

  • debug_core
  • debug_alloc
  • debug_mutex
  • debug_event
  • debug_http
  • debug_mail
  • debug_stream

error log

there are only two high level APIs user should use

  • ngx_conf_log_error(level, ): log error during conf
  • ngx_log_error(level,): log error during runtime

level can be

  • #define NGX_LOG_EMERG 1
  • #define NGX_LOG_ALERT 2
  • #define NGX_LOG_CRIT 3
  • #define NGX_LOG_ERR 4
  • #define NGX_LOG_WARN 5
  • #define NGX_LOG_NOTICE 6
  • #define NGX_LOG_INFO 7
  • #define NGX_LOG_DEBUG 8
1
2
3
4
5
6
7
ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                   "directive \"%s\" is not terminated by \";\"",
                   name->data);

ngx_log_error(NGX_LOG_CRIT, cycle->log, ngx_socket_errno,
              "the inherited socket #%d has "
              "an unsupported protocol family", ls[i].fd);
1
error_log /tmp/log info;

Note: ngx_log_error is always complied into source code, logging or not depends on what level user configured

debug log

there are several high level APIs(macros) user can use

  • ngx_log_debug0
  • ngx_log_debug1
  • ngx_log_debug2
  • ngx_log_debug3
  • ngx_log_debug4
  • ngx_log_debug5
  • ngx_log_debug6
  • ngx_log_debug7
  • ngx_log_debug8

level only limited to these below, any others like above will not be printed(like NGX_LOG_DEBUG, not printed if use ngx_log_debugx API)

  • #define NGX_LOG_DEBUG_CORE 0x010
  • #define NGX_LOG_DEBUG_ALLOC 0x020
  • #define NGX_LOG_DEBUG_MUTEX 0x040
  • #define NGX_LOG_DEBUG_EVENT 0x080
  • #define NGX_LOG_DEBUG_HTTP 0x100
  • #define NGX_LOG_DEBUG_MAIL 0x200
  • #define NGX_LOG_DEBUG_STREAM 0x400
1
2
3
4
5
6
7
ngx_log_debug1(NGX_LOG_DEBUG_CORE, cycle->log,...);

// wrong use!!! never print it out
// #define NGX_LOG_DEBUG             8
// error_log set debug log->log_level = NGX_LOG_DEBUG_ALL(0x7ffffff0)
// (log)->log_level & level == 0, so never print it out
ngx_log_debug1(NGX_LOG_DEBUG, cycle->log,...);

Note:

  • when call ngx_log_debugxxx, should never pass non-debug level to these APIs, even it’s permitted.
  • ngx_log_debugxxx is complied into source code, only when --with-debug is configured
  • logging or not depends on what level user configured
1
error_log /tmp/log debug;

inside these logging APIS

high level APIS call low level APIs with some checks, but user should never call these low level APIs

1
2
3
4
5
6
7
8
9
// log_level is user setting
// log_error check >=
#define ngx_log_error(level, log, ...)                                        \
    if ((log)->log_level >= level) ngx_log_error_core(level, log, __VA_ARGS__)

// log_debug check &, ngx_log_debugx calls ngx_log_debug
#define ngx_log_debug(level, log, ...)                                        \
    if ((log)->log_level & level)                                             \
        ngx_log_error_core(NGX_LOG_DEBUG, log, __VA_ARGS__)

For debug log(NGX_LOG_DEBUG_HTTP), it’s logged only when

  • –with-debug is configured by user
  • user set log level(log->log_level) which has that bit

Note: when error_log set debug log->log_level = NGX_LOG_DEBUG_ALL(0x7ffffff0)