When troubleshooting issues in your Asterisk system, you
will find it very helpful to refer to some sort of historical record of
what was going on in the system at the time the reported issue occurred.
The parameters for the storing of this information are defined in
/etc/asterisk/logger.conf.
Ideally, one might want the system to store a record of each and every thing it does. However, there is a cost to doing this. On a busy system, with full debug logging enabled, it is possible to completely fill the hard drive with logged data within a day or so. It is therefore necessary to achieve a balance between detail and storage requirements.
The /etc/asterisk/logger.conf file allows you to
define all sorts of different levels of logging, to multiple files if
desired. This flexibility is excellent, but it can also be
confusing.
The format of an entry in the logger.conf file is as follows:
filename=>type[,type[,type[,...]]]
There is a sample logger.conf file that comes with the Asterisk
source, but rather than just copying over the sample file, we recommend
that you use the following for your initial logger.conf file:
[general] [logfiles] console => notice,warning,error,dtmf messages => notice,warning,error ;verbose => notice,warning,error,verbose
When you have saved the file, you will need to reload the logger by issuing the following command from the shell:
$ asterisk -rx 'logger reload'*CLI> logger reloadYou can specify any filename you want, but
the special filename console will in
fact print the output to the Asterisk CLI, and not to any file on the hard
drive. All other filenames will be stored in the filesystem in the
directory /var/log/asterisk. The
logger.conf
types are outlined in Table 24.1, “logger.conf types”.
Table 24.1. logger.conf types
| Type | Description |
|---|---|
notice | You will see a lot of these during a reload, but they will also happen during normal call flow. A notice is simply any event that Asterisk wishes to inform you of. |
warning | A warning represents a problem that could be severe enough to affect a call (including disconnecting a call because call flow cannot continue). Warnings need to be addressed. |
error | Errors represent significant problems in the system that must be addressed immediately. |
debug | Debugging is only useful if you are troubleshooting
a problem with the Asterisk code itself. You would not use
debug to troubleshoot your
dialplan, but you would use it if the Asterisk developers asked
you to provide logs for a problem you were reporting. Do not use
debug in production, as the
amount of detail stored can fill up a hard drive in a matter of
days.[a] |
verbose | This is one of the most useful of the logging types, but it is also one of the more risky to leave unattended, due to the possibility of the output filling your hard drive.[b] |
dtmf | Logging DTMF can be helpful if you are getting complaints that calls are not routing from the auto attendant correctly. |
fax | This type of logging causes fax-related messages
from the fax technology backend (res_fax_spandsp or res_fax_digium) to be logged to the fax
logger. |
* | This will log EVERYTHING (and we mean everything). Do not use this unless you understand the implications of storing this amount of data. It will not end well. |
[a] This is not theory. It has happened to us. It was not fun. [b] It’s not as risky as | |
There is a peculiarity in Asterisk’s
logging system that will cause you some consternation if you are unaware
of it. The level of logging for the verbose and debug logging types is tied to the verbosity
as set in the console. What this
means is that if you are logging to a file with the verbose or debug type, and somebody logs into the CLI and
issues the command core set verbose
0, or core set debug
0, the logging of those details to your log file will
stop.
Searching through log files can be a challenge. The trick is to be able to filter what you are seeing so that you are only presented with information that is relevant to what you are searching for.
To start with, you are going to need to have an approximate idea of the time when the trouble you are looking for occurred. Once you are oriented to the approximate time, you will need to find clues that will help you to identify the call in question. Obviously, the more information you have about the call, the faster you will be able to pin it down.
If, for example, you are doing verbose logging, you should note that each distinct call has a thread identifier, which, when used with grep, can often help you to filter out everything that does not relate to the call you are trying to debug. For example, in the following verbose log, we have more than one call in the log, and since the calls are happening at the same time, it can be very confusing to trace one call:
$ tail -1000 verbose
[Mar 11 09:38:35] VERBOSE[31362] logger.c: -- IAX2/shifteight-4 answered Zap/1-1 [Mar 11 09:39:35] VERBOSE[2973] logger.c: -- Starting simple switch on 'Zap/1-1' [Mar 11 09:39:35] VERBOSE[31362] logger.c: == Spawn extension (shifteight, s, 1) exited non-zero on 'Zap/1-1' [Mar 11 09:39:35] VERBOSE[2973] logger.c: -- Hungup 'Zap/1-1' [Mar 11 09:39:35] VERBOSE[3680] logger.c: -- Starting simple switch on 'Zap/1-1' [Mar 11 09:39:35] VERBOSE[31362] logger.c: -- Hungup 'Zap/1-1'
To filter on one call specifically, we could grep on the thread ID. For example:
$ grep 31362 verbose[Mar 11 09:38:35] VERBOSE[31362] logger.c: -- IAX2/shifteight-4 answered Zap/1-1 [Mar 11 09:39:35] VERBOSE[31362] logger.c: == Spawn extension (shifteight, s, 1) exited non-zero on 'Zap/1-1' [Mar 11 09:39:35] VERBOSE[31362] logger.c: -- Hungup 'Zap/1-1'
This method does not guarantee that you will see everything relating to one call, since a call could in theory spawn additional threads, but for basic dialplan debugging we find this approach to be very useful.
Linux contains a very powerful logging engine, which
Asterisk is capable of taking advantage of. While a discussion of all
the various flavors of syslog and all the possible
ways to handle Asterisk logging would be beyond the scope of this book,
suffice it to say that if you want to have Asterisk send logs to the
syslog daemon, you simply need to specify the following in your
/etc/asterisk/logger.conf
file:
syslog.local0 => notice,warning,error ; or whatever type(s) you want to log
You
will need to have a designation in your syslog
configuration file[170] named local0, which
should look something like:
local0.* /var/log/asterisk/syslog
You can use local0 through local7 for this, but check your syslog.conf file to ensure that nothing
else is using one of those syslog
channels.
syslog[171] will allow much more powerful logging, but it will also require more knowledge than simply allowing Asterisk to log to files.
You can view the status of all your logger.conf settings through the Asterisk CLI
by issuing the command:
*CLI> logger show channelsYou should see output similar to:
Channel Type Status Configuration
------- ---- ------ -------------
syslog.local0 Syslog Enabled - NOTICE WARNING ERROR VERBOSE
/var/log/asterisk/verbose File Enabled - NOTICE WARNING ERROR VERBOSE
/var/log/asterisk/messages File Enabled - NOTICE WARNING ERROR
Console Enabled - NOTICE WARNING ERROR DTMF