Dispatcher debugging and log files

From Messaging Server Technical Reference Wiki
Jump to: navigation, search

Dispatcher error and debugging output (if enabled) are by default written to the file dispatcher.log in the MTA log directory. (But see the use_nslog Dispatcher option if you prefer to direct Dispatcher error and debugging output to an nslog file.)

Debugging output may be enabled using the debug Dispatcher option in Unified Configuration (or the option DEBUG in the Dispatcher configuration file in legacy configuration), or on a per-process level, via the PMDF_DISPATCHER_DEBUG environment variable (UNIX). (In legacy configuration, when enabling the DEBUG option in the Dispatcher configuration file, note that it may be set either globally, or (by setting it within specific SERVICE sections) only for one or more services; in particular, to enable debugging for the Dispatcher but not for its worker processes (such as SMTP server processes), it may be set within a [SERVICE=DISPATCHER] section.)

Note that as of MS 7.0.5, enabling the MTA option debug_flush will cause Dispatcher debugging to get flushed to disk immediately.

The format of records in the Dispatcher log file is:

hh.mm.ss.ss (four-digit-thread-id): debug-message

Physical lines in the Dispatcher log file are limited to 79 characters. If a record has to be continued to a second line (due to the debug-message getting "too long"), then the rest of the debug-message will be indented with white space for the time-stamp and four-digit-thread-id fields, to line up with the initial part of debug-message.

Note that the Dispatcher itself always has thread-id number 1; that is, records for the main Dispatcher process itself begin

hh.mm.ss.ss (   1): 

The debug Dispatcher option (DEBUG option in dispatcher.cnf in legacy configuration) or PMDF_DISPATCHER_DEBUG environment variable (UNIX) defines a 32-bit debug mask in hexadecimal. Enabling all debugging is done by setting the option to -1, or by defining the environment variable system-wide to the value FFFFFFFF. The actual meaning of each bit is described in Dispatcher debugging bits.

Dispatcher debugging bits
Bit Hexadecimal value Decimal value Usage
0 x00001 1 Basic Dispatcher main module debugging
1 x00002 2 Extra Dispatcher main module debugging
2 x00004 4 Dispatcher option (Unified Configuration) or configuration file (legacy configuration) logging
3 x00008 8 Basic Dispatcher miscellaneous debugging
4 x00010 16 Basic service debugging
5 x00020 32 Extra service debugging, including PORT_ACCESS mapping table probes
6 x00040 64 Process related service debugging
7 x00080 128 Shutdown queue debugging
8 x00100 256 Basic Dispatcher and process communication debugging
9 x00200 512 Extra Dispatcher and process communication debugging
10 x00400 1024 Packet level communication debugging
11 x00800 2048 Not used
12 x01000 4096 Basic Worker Process debugging
13 x02000 8192 Extra Worker Process debugging
14 x04000 16384 Additional Worker Process debugging, particularly connection handoffs
15 x08000 32768 Not used
16 x10000 65536 Basic Worker Process to Dispatcher I/O debugging
17 x20000 131072 Extra Worker Process to Dispatcher I/O debugging, including some TLS initialization debugging
20 x100000 1048576 Basic statistics debugging
21 x200000 2097152 Extra statistics debugging
24 x1000000 16777216 Log PORT_ACCESS, dns_verify_domain, and enable_rbl denials to the dispatcher.log file

See also: