Logging Settings Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Tabs
Settings Reference
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Is Logging Settings?

Logging Settings is a FreeSWITCH logging configuration module that manages console output and file logging. It configures log levels, colorization, file rotation, and module-specific mappings.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│               Logging Settings Architecture                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Logging Settings                                  │   │
│  │                                                          │   │
│  │  Tabs:                                                   │   │
│  │  ├─ Console Logging                                     │   │
│  │  │   ├─ Colorize Output                                 │   │
│  │  │   ├─ Console Log Level                               │   │
│  │  │   └─ Console Mappings                                │   │
│  │  │                                                       │   │
│  │  └─ File Logging                                        │   │
│  │      ├─ Rotate on HUP                                   │   │
│  │      └─ File Logging Profiles                           │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Generates XML                                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  console.conf.xml     logfile.conf.xml                   │   │
│  │                                                          │   │
│  │  <configuration name="console.conf">                     │   │
│  │    <param name="colorize" value="true"/>                │   │
│  │    <param name="loglevel" value="info"/>                │   │
│  │  </configuration>                                        │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Loaded by FreeSWITCH                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        FreeSWITCH Logging                                │   │
│  │                                                          │   │
│  │  Console → Terminal output                              │   │
│  │  File → /var/log/freeswitch/freeswitch.log             │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Files

File	Description
`modules/loggingSettings/`	Frontend module
console.conf.xml	Console logging config
logfile.conf.xml	File logging config

---

2. Module Overview (Commercial/Business)

Business Value

Logging Settings provides centralized log management:

Without Logging Settings	With Logging Settings
Edit XML files	Web interface
Default levels	Custom per-module
Manual rotation	Automatic rotation
No filtering	Targeted logging

Use Cases

Troubleshooting

- Enable debug for specific modules

- Track call issues

Production Optimization

- Reduce log noise

- Manage log file size

Compliance

- Log retention policies

- UUID tracking

Monitoring Integration

- Log rotation for logrotate

- Structured output

Feature Highlights

Feature	Benefit
Console Logging	Terminal output control
File Logging	Persistent log files
Log Levels	Filter by severity
Mappings	Per-module levels
Rotation	Size-based rollover
UUID Prefix	Session tracking

---

3. Module Overview (End User/Administrator)

What Can You Do?

Configure console log levels
Enable/disable colorized output
Create file logging profiles
Set log file rotation
Configure per-module log levels
Enable UUID prefixes for session tracking
Preview generated XML

Logging Settings Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Logging Settings                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Configure FreeSWITCH console and file logging                  │
│                                                                 │
│  [Console Logging] [File Logging]                               │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  Console Logging Settings                                       │
│                                                                 │
│  Colorize Output: ✓                                            │
│    Enables ANSI color highlighting in console output.           │
│                                                                 │
│  Console Log Level: [Debug] [Info] [Notice] [Warning] [Error]  │
│    ☐ Debug                                                     │
│    ✓ Info                                                      │
│    ✓ Notice                                                    │
│    ✓ Warning                                                   │
│    ✓ Error                                                     │
│    ✓ Critical                                                  │
│    ✓ Alert                                                     │
│                                                                 │
│  Console Mappings                                               │
│  Configure which log levels are displayed for specific targets. │
│                                                                 │
│  [+ Add Mapping]                                                │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Mapping Name       │ Log Levels                         │  │
│  ├────────────────────┼────────────────────────────────────┤  │
│  │ all                │ info, notice, warning, err         │  │
│  │ mod_sofia          │ debug, info, notice, warning, err  │  │
│  │ mod_lua            │ warning, err                       │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  [View XML] [Save]                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

File Logging Tab

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Logging Settings                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [Console Logging] [File Logging]                               │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  File Logging Settings                                          │
│                                                                 │
│  Rotate on HUP Signal: ✓                                       │
│    Log file reopened on HUP signal for external rotation.       │
│                                                                 │
│  File Logging Profiles                                          │
│                                                                 │
│  [+ Add Profile]                                                │
│                                                                 │
│  ▼ Profile: mainlog                                             │
│  ├─ Log File Path: [/var/log/freeswitch/freeswitch.log]        │
│  ├─ Rollover (Bytes): [10485760         ] (10MB rollover)     │
│  ├─ Maximum Rotate: [5                  ] (keep 5 files)      │
│  ├─ UUID Prefix: ✓                                             │
│  └─ Mappings:                                                   │
│     ├─ all → info, notice, warning, err, crit, alert           │
│     └─ mod_sofia → debug, info, notice, warning, err           │
│                                                                 │
│  [View XML] [Download console.conf.xml] [Download logfile.conf.xml]│
│                                                                 │
│  [Save]                                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Debug Module: Add mapping for specific module with debug level.

TIP

UUID Prefix: Enable to track logs by call session.

NOTE

Restart Required: Log configuration changes need FS reload.

---

4. Configuration Tabs

Console Logging Tab

Field	Description
Colorize Output	ANSI color highlighting
Console Log Level	Visible log levels
Console Mappings	Per-target level overrides

File Logging Tab

Field	Description
Rotate on HUP	External rotation support
File Logging Profiles	Log file configurations

Profile Settings

Field	Description
Profile Name	Identifier
Log File Path	File location
Rollover	Max size before rotation (bytes)
Maximum Rotate	Files to keep
UUID Prefix	Session UUID in logs
Mappings	Per-module log levels

---

5. Settings Reference

Log Levels

Level	Severity	Use Case
Debug	Lowest	Development, troubleshooting
Info	Low	Informational messages
Notice	Normal	Normal conditions
Warning	Medium	Potential issues
Error	High	Errors occurred
Critical	Very High	Critical conditions
Alert	Highest	Immediate action needed

Common Mappings

Mapping	Purpose
all	Default for all modules
mod_sofia	SIP signaling
mod_lua	Lua scripts
mod_dptools	Dialplan tools
mod_xml_curl	XML curl requests

Rollover Sizes

Bytes	Human Readable
1048576	1 MB
5242880	5 MB
10485760	10 MB
52428800	50 MB
104857600	100 MB

---

6. Common Scenarios & Examples

Scenario 1: Debug SIP Issues

Go to Console Logging
Add Mapping: mod_sofia = debug, info, notice, warning, err
Save
Monitor console for SIP debug

Scenario 2: Production Logging

Go to File Logging
Set Rollover = 10485760 (10MB)
Set Maximum Rotate = 10
Enable Rotate on HUP
Set "all" mapping = warning, err, crit, alert
Save

Scenario 3: Call Tracking

Go to File Logging
Enable UUID Prefix
Save
Logs now include session UUID

Scenario 4: Minimal Console

Go to Console Logging
Disable Debug, Info, Notice
Keep only Warning, Error, Critical, Alert
Save

---

7. Limitations & Important Notes

Technical Notes

NOTE

XML Generation: Creates console.conf.xml and logfile.conf.xml.

NOTE

HUP Signal: Used by logrotate for external rotation.

WARNING

Debug in Production: Avoid debug level in production (high volume).

Best Practices

Production: Use Warning+ levels only
Debug Temporarily: Turn off debug after troubleshooting
Set Rotation: Prevent disk full issues
UUID for Tracking: Enable for call troubleshooting
Logrotate Integration: Enable Rotate on HUP

Log File Locations

Distribution	Default Path
Debian/Ubuntu	/var/log/freeswitch/freeswitch.log
CentOS/RHEL	/var/log/freeswitch/freeswitch.log
Custom	Configure in profile

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
No logs	Profile disabled	Enable profile
Disk full	No rotation	Set rollover and maximum
Too verbose	Debug enabled	Reduce log levels
No colors	Colorize off	Enable Colorize Output
Logs too quiet	Levels too strict	Add info, notice levels

Check Log Configuration

Bash

# View current log level
fs_cli -x "console loglevel"

# Switch console level temporarily
fs_cli -x "console loglevel debug"

# Check log file
tail -f /var/log/freeswitch/freeswitch.log

View Generated XML

Use "View XML" button to preview configuration before saving.

---

9. Glossary

Term	Definition
Log Level	Message severity filter
Mapping	Per-module log level
Rollover	Size-based file rotation
HUP Signal	Unix signal for log rotation
UUID Prefix	Session ID in log lines
Colorize	ANSI terminal colors

---

Lua Script Status ℹ️

Configuration Module

Component	Status
Logging Settings	ℹ️ Configuration module - generates console.conf.xml and logfile.conf.xml

Logging Settings is a configuration module. Settings are stored and used to generate FreeSWITCH logging configuration files. No Lua handlers are used.

---

Documentation last updated: January 2026

Logging Settings Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Logging Settings?

Architecture

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Logging Settings Interface

File Logging Tab

Quick Tips

4. Configuration Tabs

Console Logging Tab

File Logging Tab

Profile Settings

5. Settings Reference

Log Levels

Common Mappings

Rollover Sizes

6. Common Scenarios & Examples

Scenario 1: Debug SIP Issues

Scenario 2: Production Logging

Scenario 3: Call Tracking

Scenario 4: Minimal Console

7. Limitations & Important Notes

Technical Notes

Best Practices

Log File Locations

8. Troubleshooting Tips

Common Issues

Check Log Configuration

View Generated XML

9. Glossary

Lua Script Status ℹ️

Configuration Module