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

FreeSWITCH 配置实战 20|日志等级、轮转与通话取证

English
中文

7101 拨给 7102,说是刚才打了两次,一次正常,一次没响。你到服务器上翻日志,发现当前文件是新开的,前一通已经去了归档。日志找到了,又有两组号码相近、时间挨得很近的记录。遇到这种情况,可以先拿到一条能定位呼叫的标记,再用它去查轮转前后的文件。

这期用 FreeSWITCH v1.11.3 做一个内网练习。7101 拨测试短号 7320,由拨号计划接到已注册的 7102。拨测两次,中间触发一次文件轮转。验收时保留两条 NOTICE 标记,分别来自旧文件和新文件,并能用其中的通道 UUID 找回相关日志。需要一台自己有维护权限的测试节点,已具备 7101 与 7102 的正常互拨和 fs_cli 连接。

先把落盘规则配清楚

用 fs_cli 查运行中的配置根目录和日志目录。找到配置根目录下的 autoload_configs/logfile.conf.xml,先备份。示例是一份完整的文件,适合只有默认日志 profile 的隔离测试节点。已有采集配置或多个 profile 的节点,应只在实验环境改对应的 profile,并记下原来的文件路径和级别。

# 在 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>

这份配置没有填 logfile。v1.11.3 的模块会用运行日志目录下的 freeswitch.log。如果实际需要独立路径,可以在 profile 的 settings 里加 logfile,填写绝对路径。路径所在目录要提前创建,FreeSWITCH 的运行账号需要能写文件,也要能在该目录内创建和改名,轮转时才有地方落新文件。

rollover 用字节。5242880 是 5 MiB,适合练习时观察文件变化,生产环境要看日志写入量和磁盘预算。maximum-rotate 这里是 4,编号归档最多保留 4 份,另有一份在写的文件。按每份约 5 MiB 粗算是 25 MiB,写入越过阈值以及目录中原有的旧归档都会影响实际占用。调小保留数量时,原先遗留的高编号文件也可能还在目录里,核算容量要看磁盘实况。

rotate-on-hup 配在外层 settings,设为 true 时,HUP 事件会让 mod_logfile 的各个 profile 都轮转。rollover 设为 0 时关闭按大小轮转,HUP 路径仍由 rotate-on-hup 决定。已有外部日志工具负责改名的节点,通常由外部工具改名,再让进程重开文件,避免两边同时轮转同一个路径。本期给 maximum-rotate 一个明确正数。v1.11.3 里省略它和显式填 0 会走不同分支,配置里写明归档份数更容易对照验收。

uuid 开着时,带会话上下文的日志会加上该通道的 UUID。模块加载、文件打开这类进程级日志可能没有通道 UUID。mappings 中的 all 匹配所有来源,后面的值按等级逐项放行,NOTICE 作为验收标记,DEBUG 留作对照。若要临时抓某个源码文件的细节,可以给文件名单独加一条 map。源码按全局、文件、函数等路径判断,只要前面的匹配放行,后面更窄的 map 就拦不回来。想增加某个文件的 DEBUG,可以用单独映射,想用特定文件映射压掉全局已允许的级别则行不通。

给 7101 到 7102 的拨测留一条能找回来的标记

确认短号 7320 未被现有拨号计划占用。默认 context 可把以下内容存为 dialplan/default/20_fs20_log_check.xml,实际要看当前 context 包含哪个目录。示例用注册目录中的 domain_name 找 7102,分机属于独立域时,把目标换成实际的目录用户和域。call_timeout 的单位是秒,本例给出 15 秒让被叫接听。

两条 log 动作放在 bridge 前。这样即使出腿稍后失败,仍能查到呼叫曾经进入这条测试路由。标记只写测试短号和目标分机,不记录认证字段或通话正文。

<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'

reloadxml 由拨号计划读取新的 XML。文件 logger 的 profile 是模块加载时建立的,单独执行 reloadxml 后不能据此判断轮转参数生效了。只在测试节点或维护窗口执行 reload mod_logfile,确认返回里模块确实重新加载成功。重新加载期间,磁盘日志写入可能短暂中断。改完先查文件是否可以打开,再拨 7320,免得把权限问题误判为拨号计划没命中。

拨两次,跨文件对照

用 7101 拨 7320,7102 接听后挂断。记录第一通的真实时间与日志里的 A-leg UUID。当前文件应出现 NOTICE 标记。DEBUG 标记按本例配置不会进入该文件,即使你在交互式控制台看到了它。控制台显示和文件落盘有独立的过滤设置,同一行在两处显示不同很常见。

第一通结束后,用 fsctl send_sighup 触发 HUP。观察 freeswitch.log.1 里是否能找到第一通,新的 freeswitch.log 是否已经就绪。再从 7101 拨一次 7320,接听并挂断。第二通应该有新的 UUID,标记应写进新文件。执行前确认在测试节点上,命令会触发相关 HUP 处理。另一个名字有点像的 fsctl hupall 会挂断会话,和这里的轮转是两件事。

# 用实际 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"

这验证了手动轮转和继续写入。要验收大小触发,可以另用一台隔离实例,把 rollover 临时改成更小的测试值,在几次正常拨测后观察文件过阈值时有没有自动生成归档。完成后把测试阈值撤回。在生产上衡量留存时长,可以看实际写入速度。在同样 5 MiB 的配置下,开启大量 DEBUG 会明显加快归档覆盖。

遇到缺行,按现象找原因

  • 接通却找不到 NOTICE。先看 7320 是否命中这条路由,再确认实际 log_dir、运行用户权限和文件 level map。fs_cli 里临时调了显示等级时,也要到真实文件再查一次。
  • 归档出现,但新文件没有第二通。查模块重开文件有没有报错,再看采集程序跟的是文件名还是旧文件句柄。用 ls -li 对照文件编号与 inode,能区分“FreeSWITCH 没写”和“采集端还在追旧文件”。
  • 同一通电话搜到多个 UUID。7101 的 A-leg 和 7102 的 B-leg 各有自己的通道标识。先沿验收标记定位 A-leg,再用话单或同时段 ESL 事件里已有的桥接关联确认 B-leg。SIP Call-ID 也属于信令对话标识,跨两腿查找时保留各腿实际值。
  • 当前文件只看到服务重载后。查 .1 等归档,记录节点、时区和呼叫时间。若系统由 systemd 接管,可以按服务名和时间窗口导出 journal 辅助确认重启与系统报错。能看到哪些 FreeSWITCH 消息取决于该服务是否把相应输出交给了 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'

把样例里的日期和时间换成真正的事发范围。发给同事前,只截取定位问题所需的记录,按项目规则处理号码、地址、鉴权头和其他敏感字段。回退时移除 20_fs20_log_check.xml,恢复备份的 logfile.conf.xml,再重新加载 XML 和 mod_logfile。复查分机正常互拨,并确认恢复后的路径仍在写。本文核对了 v1.11.3 模板和源代码,拨测步骤及文件结果需在自己的测试节点验收。

参考资料


评论