Administrator
发布于 2026-11-17 / 3 阅读
0
0

FreeSWITCH Lab 20 | Log Levels, Rotation, and Call Evidence

English
中文

Two calls from extension 7101 to 7102 can look alike in a log even if only one worked. Rotation adds another wrinkle. The first attempt may be in an archive and the second in the file being written now.

This lab targets FreeSWITCH v1.11.3 on an internal test node. Dial 7320 from 7101 to bridge to registered extension 7102. Place two calls and rotate the log between them. Keep a NOTICE marker from each file and use its channel UUID to find related records. Start with working calls between the two extensions and administrative access to fs_cli.

Configure the file logger

Get the live configuration and log directories. Back up autoload_configs/logfile.conf.xml under the configuration root. The complete example assumes an isolated node with only the default logger profile. On a node with multiple profiles or an existing collector, limit the change to the test profile and save its original settings.

# 在 FreeSWITCH 所在的 Linux 测试节点运行。
fs_cli -x 'global_getvar conf_dir'
fs_cli -x 'global_getvar log_dir'
fs_cli -x 'module_exists mod_logfile'
<configuration name="logfile.conf" description="File Logging">
  <settings>
    <!-- 在测试节点用 HUP 手动验证轮转。 -->
    <param name="rotate-on-hup" value="true"/>
  </settings>
  <profiles>
    <profile name="default">
      <settings>
        <!-- 未写 logfile 时,使用运行目录中的 freeswitch.log。 -->
        <!-- 5 MiB,按字节计算。 -->
        <param name="rollover" value="5242880"/>
        <!-- 保留 4 份编号归档,另有一份当前文件。 -->
        <param name="maximum-rotate" value="4"/>
        <!-- 有通道上下文的记录加上会话 UUID。 -->
        <param name="uuid" value="true"/>
      </settings>
      <mappings>
        <!-- 枚举需要写入该文件的等级,保留 NOTICE 验收标记。 -->
        <map name="all" value="notice,warning,err,crit,alert"/>
      </mappings>
    </profile>
  </profiles>
</configuration>

With logfile omitted, the module uses freeswitch.log in the running log directory. To use another destination, specify an absolute path in the profile settings. The service account needs to write the file, create the replacement, and rename entries in the parent directory.

The rollover value is in bytes. The example uses 5 MiB, with four numbered archives and one current file. That is roughly 25 MiB before record-size overruns and pre-existing archives. Old files can remain after lowering the retention count, so check actual disk usage. Zero rollover disables size-based rotation. Set a positive maximum-rotate explicitly: in v1.11.3, omission and explicit zero take different paths.

The outer rotate-on-hup setting enables rotation for all mod_logfile profiles when the HUP event is received. If another tool owns rotation, it can rename the old file and make FreeSWITCH reopen its output. Coordinate the tools so they do not rotate the same file independently.

With uuid enabled, records that carry session context get the channel UUID. Process messages may have none. The all mapping covers every source and lists the accepted levels individually. Retain NOTICE for the test marker. You can add DEBUG for a specific source file through a separate map. A narrower match cannot remove a level already admitted by the global mapping.

Add a marker to the route to 7102

Confirm that 7320 is unused. In the default context, save this as dialplan/default/20_fs20_log_check.xml. Use the directory included by the actual context if yours differs. The bridge looks up 7102 in domain_name. Use the registered user's real directory domain if the lab uses a dedicated one. The call timeout is 15 seconds. Markers run before the bridge, so they survive an outbound leg failure. They contain the lab short code and destination extension without credentials or call content.

<include>
  <extension name="fs20-log-check">
    <!-- 仅匹配测试短号 7320。 -->
    <condition field="destination_number" expression="^7320$">
      <!-- 在发起出腿前记录同一 A-leg 的两种等级。 -->
      <action application="log" data="NOTICE fs20-log-check route=7320 target=7102"/>
      <action application="log" data="DEBUG fs20-log-debug route=7320"/>
      <action application="set" data="call_timeout=15"/>
      <!-- 使用本域目录用户 7102,继续沿用分机注册配置。 -->
      <action application="bridge" data="user/7102@${domain_name}"/>
    </condition>
  </extension>
</include>
# 保存配置和拨号计划后,检查每行命令的返回消息。
fs_cli -x 'reloadxml'
fs_cli -x 'reload mod_logfile'

Reload XML to refresh the dialplan. File logger profiles are built during module loading. Reload mod_logfile on a test node or in a maintenance window and verify the response. File logging can be briefly interrupted. Confirm the file is writable before placing test calls.

Compare the archive with the active file

Dial 7320 from 7101, answer at 7102, then hang up. Note the call time and the real A-leg UUID. Expect the NOTICE marker in freeswitch.log. The DEBUG marker is filtered out of that file, even if a separately configured console shows it.

After the first call, trigger HUP with fsctl send_sighup on the lab node. Check that freeswitch.log.1 contains the first marker and that the active file has reopened. Call again, answer, and hang up. Expect a different UUID and a new marker in the active file. The similarly named fsctl hupall hangs up sessions and has a separate purpose.

# 用实际 log_dir。这里仅把常见目录设作示例。
LOG_DIR=/var/log/freeswitch
grep -F 'fs20-log-check route=7320' "$LOG_DIR/freeswitch.log" | tail -n 3

# 第一次拨测挂断后,在测试节点触发轮转。
fs_cli -x 'fsctl send_sighup'
ls -li "$LOG_DIR/freeswitch.log" "$LOG_DIR/freeswitch.log.1"

# 第二次拨测后,用各自真实的通道 UUID 对照两个文件。
grep -nF 'fs20-log-check route=7320' \
  "$LOG_DIR/freeswitch.log.1" "$LOG_DIR/freeswitch.log"

This proves that the lab can rotate manually and keep writing. Test size-based rotation separately on an isolated instance with a smaller temporary test threshold and a few normal calls, then restore the value. DEBUG can consume archives more quickly. Estimate the retention window from measured write volume rather than file count alone.

Check which part of the trail is missing

  • If the call connects but the marker is absent, check the matched route, actual log directory, service account permissions, and file logger level map. A change in fs_cli display settings does not verify file output.
  • If the archive appears but the second marker does not, look for errors reopening the file. Check whether the collector follows the path or the old file handle. Compare file names and inode numbers with ls -li.
  • If a single call has multiple UUIDs, begin with the A-leg marker. Use a bridge association already recorded in the CDR or contemporaneous ESL events to locate the B-leg. SIP Call-ID identifies the signaling dialog. Keep the actual value for each leg.
  • If the current file only goes back to the last reload, check its archives as well. For services run under systemd, inspect the unit journal in the same time window for service events and errors. It only contains the output made available to the journal.
# 示例对应北京时间 10:00 至 10:10,服务名换为本机实际单元。
journalctl -u freeswitch.service --no-pager -o short-iso \
  --since '2026-11-17 02:00:00 UTC' \
  --until '2026-11-17 02:10:00 UTC'

Replace the date and times with the incident window. Share only the necessary records and handle numbers, addresses, authorization headers, and other sensitive values according to your rules. To roll back, remove 20_fs20_log_check.xml, restore logfile.conf.xml, and reload XML and mod_logfile. Verify normal extension calls and that logging continues at the restored path. These steps were checked against the v1.11.3 template and source. The call and file outcomes should be verified on your own test node.

References


评论