Logging
General log
Flexisip writes its log messages into /var/opt/belledonne-communications/log/flexisip/flexisip-<server>.log, where <server> is replaced by the kind of the server: proxy or presence or conference. The directory where log files are placed may be changed thanks to log-directory parameter in [global] section.
Flexisip also uses Syslog for logging. These messages are written in /var/log/*, according Syslog convention, or are available by journalctl command if your system is set to map Syslog messages into systemd-journald.
The verbosity of each previously introduced backend can be set by using the log-verbosity and syslog-verbosity parameters. Available verbosity level are: debug, message, warning, error. There is no way of disabling one of these backend today.
# Set the log file to the maximum verbosity
log-level=debug
# Set Syslog backend to print error messages only
syslog-level=error
Contextual logs (proxy only)
Understanding contextual logs
When running on production serving million of users, it is unrealistic to run with a log verbosity level below warnings: it will too much affect the performance of the server, in terms of CPU and disk usage.
However, it may be desired to obtain debug logs for a limited subset of SIP messages being processed by Flexisip, in order for example to troubleshoot a calling issue affecting a particular user.
This is made possible thanks to contextual logs, which are controlled by two properties of Global section of flexisip.conf:
# When matched, logs are output provided that their level is greater
# than the value defined in contextual-log-level. The definition
# of the SIP boolean expression is the same as for entry filters
# of modules, which is documented here: https://wiki.linphone.org/xwiki/wiki/public/view/Flexisip/Configuration/Filter%20syntax/
# Default value:
contextual-log-filter=
# Verbosity of contextual logs to output when the condition defined
# in 'contextual-log-filter' is met.
# Default value: debug
contextual-log-level=debug
The language used to define SIP boolean expression is fully documented here. Here are some examples to illustrate:
contextual-log-filter=(from.uri.user == 'alice' || to.uri.user == 'alice')
# Enable debug logs relative to the processing of SUBSCRIBE/NOTIFY requests
contextual-log-filter=request.method == 'SUBSCRIBE || request.method == 'NOTIFY'
# Enable debug logs relative to the processing of a 488 error response from a client
contextual-log-filter=status.code == '488'
Activating contextual logs at run-time
Since troubleshooting could be necessary at any time on a production system, but restarting the service to have the configuration taking into effect is not an option, it is possible to dynamically change the values of the contextual-log-filter and contextual-log-level properties. The change is temporary: the flexisip.conf configuration file is not modified and after a restart the values from flexisip.conf will be used.
To change these values, use the flexisip-cli.py tool (included in flexisip packages in /opt/belledonne-communications/bin). In the following example, we setup a filter to enable logging of everything related to a REGISTER request coming from french phone numbers:
Pay attention to the escaping: indeed the shell is interpreting some of the operators used in flexisip's sip boolean expression language. In particular:
- words enclosed by single quotes must have single quotes escaped by '\' character
- operators like '&&', '||' must be surrounded by single quotes to avoid the shell interpreter to process them.
- parenthesis must be preceded by '\' character.
To control that your sip boolean expression has correctly been passed to the server, flexisip_cli.py displays the expression that was interpreted by the flexisip server:
Event log
The event log only records the incoming requests and the status code that has been replied by the proxy. The following kind of request are supported: registration, call initiation (INVITE), message delivery and authentication trying.
Information about the value of some headers are available for each request. Here is the list of the available headers: From, To, Call-ID, User-Agent.
All parameters that concern "event log" logger are place in [event-logs] section.
By default, event log entries are written on the filesystem using a file per user located in <log_dir>/users/<user_domain>/<user_name>/<date>.log, where <log_dir> is defined by filesystem-directory parameter. The entries may also be written in a SQL database by setting logger=database. Of course, database-backend and database-connection-string must also be set. The schema used for event logs are describe here.
[event-logs]
enabled=true
logger=filesystem
filesystem-directory=/var/opt/belledonne-communications/log/flexisip
# example using a MySQL database
[event-logs]
enabled=true
logger=database
database-backend=mysql
database-connection-string=db='mydb' user='myuser' password='mypass' host='myhost.com'
Log rotation
Flexiisp relies on logrotate for log rotation of general logs. By default, the logs in /var/opt/belledonne-communications/log/flexisip directory are rotated and the rotation is triggered when the log size reach 500MB, keeping seven archives. These limits may be changed by editing /etc/logrotate.d/flexisip-logrotate. See logrotate(8) manual for more information about logrotate syntax.