Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/signalwire/freeswitch/llms.txt

Use this file to discover all available pages before exploring further.

FreeSWITCH uses a modular logging system made up of three independent output modules: mod_console for terminal output, mod_logfile for persistent log files, and mod_syslog for integration with the system logging daemon. Each module is configured independently, and all three can be active simultaneously. Every log message carries a severity level, an originating source file or function name, and an optional session UUID — making it straightforward to filter and correlate events from a specific call.

​
Log Levels

FreeSWITCH uses eight named severity levels. Each level has a numeric value; lower numbers indicate higher severity. When you set a log level, you receive messages at that level and all higher-severity levels.
LevelNameNumericMeaning
CONSOLEconsole1Messages displayed only in the interactive console (not written to files).
ALERTalert2Conditions that require immediate human intervention.
CRITcrit3Critical failures — the switch may not be functioning correctly.
ERRerr4Error conditions that affect a feature or call, but not the whole switch.
WARNINGwarning5Potentially harmful situations worth monitoring.
NOTICEnotice6Normal but significant events such as registrations and call setups.
INFOinfo7General informational messages about switch operation.
DEBUGdebug8Verbose developer-level output; not recommended for production.
On busy production systems, consider setting the console and file log level to warning (5) or notice (6) during normal operation to reduce I/O overhead and make genuine errors easier to spot. You can always raise the level temporarily for a debugging session with log 7 and then bring it back down with log 5.

​
Console Logging (mod_console)

mod_console writes log output directly to the terminal when FreeSWITCH is running in interactive console mode (-c) or foreground mode (-nf). It supports colorized output and per-source log filtering through a <mappings> section. Configuration is in conf/autoload_configs/console.conf.xml: 
<configuration name="console.conf" description="Console Logger">
  <!-- Map log levels to source files or functions.
       name can be a file name, function name, or 'all'.
       value is one or more of: debug,info,notice,warning,err,crit,alert,all -->
  <mappings>
    <map name="all" value="console,debug,info,notice,warning,err,crit,alert"/>

    <!-- Example: suppress everything except errors, then add full detail
         for a specific module:
    <map name="all"      value="err,crit,alert"/>
    <map name="mod_sofia" value="all"/>
    -->
  </mappings>
  <settings>
    <!-- Set to false to disable ANSI color output -->
    <param name="colorize" value="true"/>
    <!-- Uses the $${console_loglevel} variable from vars.xml -->
    <param name="loglevel" value="$${console_loglevel}"/>
  </settings>
</configuration>

​
Per-Source Filtering

The <mappings> section lets you reduce noise by showing only high-severity messages globally while enabling full verbosity for a specific source file or function. The name attribute accepts:
  • all — matches every log source (overrides other entries if present)
  • A filename such as mod_sofia.c — matches messages from that source file
  • A function name such as switch_core_state_machine — matches messages from that function
<!-- Show only errors and above globally, but full debug for Sofia and the state machine -->
<map name="all"                          value="err,crit,alert"/>
<map name="sofia.c"                      value="notice"/>
<map name="switch_core_state_machine.c"  value="all"/>

​
File Logging (mod_logfile)

mod_logfile writes log output to one or more persistent log files. It supports automatic rotation by file size and a configurable maximum number of retained rotated files. Configuration is in conf/autoload_configs/logfile.conf.xml: 
<configuration name="logfile.conf" description="File Logging">
  <settings>
    <!-- true: rotate the current log on SIGHUP; false: close and reopen -->
    <param name="rotate-on-hup" value="true"/>
  </settings>
  <profiles>
    <profile name="default">
      <settings>
        <!-- Explicit log file path. If omitted, defaults to
             the FreeSWITCH log directory/freeswitch.log -->
        <!-- <param name="logfile" value="/var/log/freeswitch/freeswitch.log"/> -->

        <!-- Rotate when the file reaches this size in bytes (0 = never).
             1048576000 = 1 GB -->
        <param name="rollover" value="1048576000"/>

        <!-- Maximum number of rotated files to keep before wrapping.
             When enabled, filenames do NOT include a date stamp. -->
        <param name="maximum-rotate" value="32"/>

        <!-- Prefix every log line with the channel UUID for easy grepping -->
        <param name="uuid" value="true"/>
      </settings>
      <mappings>
        <!-- Log everything to the file -->
        <map name="all" value="console,debug,info,notice,warning,err,crit,alert"/>
      </mappings>
    </profile>
  </profiles>
</configuration>

​
Multiple Log Profiles

You can define additional <profile> blocks to write different subsets of log data to different files. For example, write only errors to a separate error log: 
<profile name="errors-only">
  <settings>
    <param name="logfile" value="/var/log/freeswitch/errors.log"/>
    <param name="rollover" value="104857600"/>
  </settings>
  <mappings>
    <map name="all" value="err,crit,alert"/>
  </mappings>
</profile>

​
Syslog (mod_syslog)

mod_syslog forwards FreeSWITCH log messages to the host operating system’s syslog daemon (rsyslog, syslog-ng, journald, etc.), enabling centralized log aggregation and standard log-rotation tooling. Configuration is in conf/autoload_configs/syslog.conf.xml: 
<configuration name="syslog.conf" description="Syslog Logger">
  <settings>
    <!-- syslog facility: user, daemon, local0–local7, etc. -->
    <param name="facility" value="user"/>
    <!-- Program identifier that appears in syslog entries -->
    <param name="ident"    value="freeswitch"/>
    <!-- Minimum severity level to forward to syslog -->
    <param name="loglevel" value="warning"/>
    <!-- Include the channel UUID in each syslog entry -->
    <param name="uuid"     value="true"/>
  </settings>
</configuration>
The loglevel parameter uses the same severity names as other logging modules (debug, info, notice, warning, err, crit, alert). Setting it to warning is a sensible default for syslog — it captures actionable events without flooding the system log.

​
Setting Log Level at Runtime

You can change the console log verbosity while FreeSWITCH is running without editing any configuration files or restarting. Changes take effect immediately and persist until the next restart. 
# At the interactive console or via fs_cli:

# Show INFO and all higher-severity messages
freeswitch> log 7

# Show only WARNING and higher (err, crit, alert)
freeswitch> log 5

# Silence all console log output
freeswitch> log 0

# Equivalent using fsctl with a named level
freeswitch> fsctl loglevel warning
freeswitch> fsctl loglevel debug
The numeric values map directly to the level table above (DEBUG=8, INFO=7, NOTICE=6, WARNING=5, ERR=4, CRIT=3, ALERT=2). Level 0 suppresses all console output.

​
Log Rotation

mod_logfile automatically rotates the active log file when it reaches the size configured in rollover. You can also trigger an immediate rotation without restarting the switch.

​
Triggering Rotation Manually

# Send SIGHUP to the FreeSWITCH process — triggers log rotation
kill -HUP $(cat /var/run/freeswitch/freeswitch.pid)

​
Triggering Rotation via the Console

freeswitch> fsctl send_sighup
When rotate-on-hup is true in logfile.conf.xml, a SIGHUP signal causes the current log file to be renamed with a timestamp (or a numeric suffix if maximum-rotate is set) and a new log file to be opened. This is compatible with external rotation tools such as logrotate using the postrotate directive.

​
Example logrotate Configuration

/var/log/freeswitch/freeswitch.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    postrotate
        kill -HUP $(cat /var/run/freeswitch/freeswitch.pid 2>/dev/null) 2>/dev/null || true
    endscript
}

​
Debugging Calls

When troubleshooting a specific call or SIP negotiation failure, several runtime commands expose additional detail without requiring a log level change across the entire system.

​
SIP Message Tracing

# Enable SIP message tracing for all profiles
freeswitch> sofia global siptrace on

# Enable tracing for a single profile only
freeswitch> sofia profile internal siptrace on

# Disable tracing
freeswitch> sofia global siptrace off

​
Sofia Log Level

The sofia loglevel command adjusts the verbosity of the Sofia-SIP stack’s internal logging independently of the FreeSWITCH log level. Level 9 is the most verbose. 
# Maximum Sofia verbosity for all sub-components
freeswitch> sofia loglevel all 9

# Restore default Sofia log level
freeswitch> sofia loglevel all 0
Sofia sub-components that can be targeted individually include: default, tport, iptsec, nea, nta, nth_client, nth_server, nua, soa, sresolv, and stun.

​
Per-Call Debugging

For a targeted view of a single session, you can filter log output by UUID in the mod_logfile profile (using the uuid option) and then grep the log file: 
grep "3f6a1b2c-1234-4abc-8def-000000000001" /var/log/freeswitch/freeswitch.log

Build docs developers (and LLMs) love

Get started for freeTalk to us