Logging with FreeSWITCH

Logging is an integral part of any properly managed communication operation. The capability of tracing the minimal details of protocol exchanges and the paths through the internal software mechanisms can be invaluable for pinpointing the intermittent problem of a customer.

There are two main media for logging in FreeSWITCH: the console, for example the fs_cli application, and the log file. Both options use the same mechanism to show or save information.

By default, FreeSWITCH logs all information into one log file at the DEBUG level (the highest detail, producing the most quantity of information). The log file is created and managed by module mod_logfile, configured through logfile.conf.xml. By default, that single log file is called freeswitch.log and is located in freeswitch/log/.

The general format for the log lines is: call-uuid YYYY-MM-DD hh:mm:ss:nnnnnn [LEVEL] source_file_name:line_numberfunction_name() <log data>.

Log levels go from EMERG (Level 0) to DEBUG (Level 7), each progressive level enabling recording of more information than the preceding, to culminate with DEBUG that allows for a tremendous quantity of information on the internals of each FreeSWITCH function, useful both to FS core developers, but in some cases also to determine what is going wrong with a call.

It is possible to generate multiple log files containing information at different levels, and also files tracing the inner working of just one function. That can be managed by creating different logging profiles in logfile.conf.xml.

Using profiles, you can build a mapping that will record ERROR, CRITICAL and ALERT information for all modules (default) while specifying higher levels for specific internal functions and the maximum DEBUG level for a particular module. The profile also contains the name and place of the log file, while rotation can be specified as activated by HUP signal and/or by reaching a configured size (defaults to 10 MB).

Debug loglevel is very verbose, and you don't want it to be activated all of the time, because on a busy server it would quickly fill an inordinate amount of disk space and because disk I/O operations would exact too much in terms of context switches and wait states.

Tip

You would normally run FS with loglevel 3 or 4 (error or warning), and you would notch up to loglevel 7 from FS console only when needed, with:

fsctl loglevel [loglevel]

Don't forget to lower the loglevel, after gathering the information you're looking for. To modify loglevel only for a particular channel (uuid), from FS console you use:

uuid_loglevel [uuid] [loglevel] 

While in dialplan you can use session_loglevel app:

<action application="session_loglevel" data="loglevel "/>

The FreeSWITCH logging system is much more flexible than this. Actually you can specify in logfile.conf.xml a different loglevel for each single C source file and/or for each single C function. This is almost never useful in a production environment, but is very useful when debugging the source code itself (for example to FreeSWITCH project developers). You can find full instructions and explanation for this finer loglevel mapping in the comments embedded at the head of the vanilla distributed console.conf.xml (console uses the same mapping method as logfile).

All of the aforementioned methods and techniques apply to console logging too, configured by console.conf.xml. On console, the FreeSWITCH administrator will see all the same information we've listed scrolling by, smartly colorized for an intuitive interpretation. It is possible to change in real time and live, both the level of console logging and the source of it, for example global, modules, or functions.

Another important tool related to logging and debugging FreeSWITCH operation is the capability of mod_sofia to show (and optionally log to a specified level) all of the SIP and SDP packets for a call, or for an interface (SIP profile), or globally. This is extremely useful both at setup time and for debugging problems and malfunctions. You can rely on it instead of going back and forth with ngrep and/or wireshark.

As a FreeSWITCH administrator you will deal with logging all the time, be it reading the log output that scrolls on the FS console in real time as it happens, or by perusing and analyzing the debug logfile to identify what problem lead to a failed call, or by collecting durations, destinations, originator, and monetary costs of each and every call from CDRs.

Logging is what gives FreeSWITCH administrators the information on which to base most of their activity.