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:


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'

or from the Asterisk CLI:

*CLI> logger reload

You 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

noticeYou 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.
warningA 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.
errorErrors represent significant problems in the system that must be addressed immediately.
debugDebugging 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]
verboseThis 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]
dtmfLogging DTMF can be helpful if you are getting complaints that calls are not routing from the auto attendant correctly.
faxThis 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 debug, since it’ll take months to fill the hard drive, but the danger is that it will happen, say, a year later when you’re on summer vacation, and it will not immediately be obvious what the problem is. Not fun.


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.

Reviewing Asterisk Logs

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

which would give us:

[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.

Logging to the Linux syslog Daemon

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.

Verifying Logging

You can view the status of all your logger.conf settings through the Asterisk CLI by issuing the command:

*CLI> logger show channels

You 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

[170] Which will normally be found at /etc/syslog.conf.

[171] And rsyslog, syslog-ng, and what-all-else.