MediaMTX 日志配置实战日志级别、多目标输出、JSONL 结构化日志与日志轮转【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtxMediaMTX 内置了一套轻量、可扩展的日志系统通过logLevel、logDestinations、logFile、sysLogPrefix、logStructured等配置项即可在不重启编译的前提下完成日志级别控制、stdout / 文件 / syslog 多目标输出、JSONL 结构化日志以及基于 logrotate 的日志轮转。读完本文你将掌握 MediaMTX 日志从级别过滤—目标分发—结构化格式化—轮转归档的完整链路并能直接在生产环境中落地一套可查询、可采集、可归档的日志方案。日志级别用 logLevel 控制输出粒度MediaMTX 提供 4 个日志级别由配置项logLevel指定# Verbosity of the program; available values are error, warn, info, debug. logLevel: info取值含义典型场景error仅输出错误生产环境的最小化输出适合日志量大、只关心故障的场景warn输出警告与错误关注潜在风险但不希望被常规信息刷屏info输出常规信息、警告与错误默认值默认配置记录服务启动、监听端口、连接会话等关键事件debug输出全部日志含调试信息排查问题、分析推拉流细节时使用从源码实现看级别过滤发生在最前端的入口处internal/logger/logger.go 的Log()方法首先执行if level l.Level { return }低于配置级别的事件会被直接丢弃不会进入任何输出目标因此调整logLevel对性能的影响很小。级别常量定义在 internal/logger/level.go 中按Debug → Info → Warn → Error递增logLevel: info即意味着 Info、Warn、Error 三级事件都会被输出。级别字符串到内部枚举的解析由 internal/conf/log_level.go 完成它同时支持 JSON 与环境变量两种反序列化方式非法取值会直接报错invalid log level: xxx。根目录的默认配置文件 mediamtx.yml 中即采用logLevel: info如果你希望控制台安静一些可以改为logLevel: warn或logLevel: error。日志输出目标stdout / file / syslog 可组合logDestinations决定日志写往哪些目标它是一个数组可以同时启用多个目标事件会并发分发到所有已启用的目标# Destinations of log messages; available values are stdout, file and syslog. logDestinations: [file] # If file is in logDestinations, this is the file which will receive the logs. logFile: mediamtx.log默认情况下日志只打印到控制台stdout。可用的目标值在 internal/conf/log_destination.go 中定义并解析三个合法值为stdout、file、syslog在 internal/logger/logger.go 的Initialize()中会按目标类型逐一创建对应的输出处理器stdout 目标写入标准输出、file 目标打开指定文件、syslog 目标连接系统日志服务。目标列表也支持通过环境变量以逗号分隔传入解析逻辑见 internal/conf/log_destinations.go。写入文件logFile当logDestinations包含file时日志会追加写入logFile指定的文件默认mediamtx.log。从 internal/logger/destination_file.go 可以看到文件以O_APPEND|O_CREATE|O_WRONLY模式打开、权限为0644因此进程启动时文件不存在会自动创建且始终以追加方式写入不会覆盖历史日志。日志器内部通过互斥锁串行化写入见logger.go的mutex字段保证多条日志并发产生时不会交错。写入系统日志syslog当logDestinations包含syslog时日志会发给系统日志服务# Destinations of log messages; available values are stdout, file and syslog. logDestinations: [syslog] # If syslog is in logDestinations, use prefix for logs. sysLogPrefix: mediamtxsysLogPrefix指定日志的标识前缀默认mediamtx。从 internal/logger/destination_syslog_other.go 的实现看它调用syslog.New(syslog.LOG_DAEMON, prefix)连接系统 syslogfacility 为 daemon并把四个日志级别分别映射为 syslog 的Debug / Info / Warning / Err方法与 stdout、file 目标不同syslog 目标只发送消息正文——时间戳和级别由 syslog 服务自身负责附加。注意该实现位于带!darwin !windows构建标签的文件中即 Linux 等 Unix 系平台可用Windows 与 macOS 有各自的适配实现。在 systemd 环境下日志会进入 journald可以通过标识符直接查询journalctl SYSLOG_IDENTIFIERmediamtx以 systemd 服务运行时的日志查询如果 MediaMTX 还以系统服务方式运行配置方法见 17-start-on-boot.md则可以借助 systemd 的 unit 名过滤全部日志无需关心sysLogPrefixjournalctl -u mediamtx这种方式会同时带出服务自身的启动、停止、崩溃等 systemd 事件与 MediaMTX 的输出日志排查服务为什么没起来类问题非常高效。结构化日志logStructured 输出 JSONL主流日志采集器Loki、Logstash、CloudWatch、fluentd 等在解析带固定字段的 JSON LinesJSONL时比解析自由文本可靠得多。MediaMTX 通过logStructured开启结构化输出# When destination is stdout or file, emit logs in structured format (JSONL). logStructured: true开启后每条日志是一个单行 JSON 对象形如{timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[RTSP] listener opened on :8554 (TCP/RTSP), :8000 (UDP/RTP), :8001 (UDP/RTCP)} {timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[RTMP] listener opened on :1935} {timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[HLS] listener opened on :8888} {timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[WebRTC] listener opened on :8889 (TCP/HTTP), :8189 (UDP/ICE)} {timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[SRT] listener opened on :8890 (UDP)}每个 JSON 对象包含三个字段timestampRFC3339Nano 格式的时间戳精确到纳秒并含时区偏移由 destination_stdout.go 与 destination_file.go 中的t.Format(time.RFC3339Nano)生成level级别缩写DEB/INF/WAR/ERRmessage经过转义的完整日志消息含[RTSP]、[HLS]之类的协议模块前缀。结构化输出仅对stdout与file两个目标生效配置注释与代码均如此规定syslog 目标天然由系统日志服务结构化因此不受影响。值得注意的是非结构化模式下 stdout / file 输出的是YYYY/MM/DD HH:MM:SS INF message形式的纯文本且 stdout 在连接终端时会自动着色term.IsTerminal检测见 destination_stdout.go而写入文件与结构化模式不会带颜色。日志文件轮转借助 logrotate 归档旧日志MediaMTX 自身不提供内置的日志分割机制官方推荐使用外部工具定期轮转rotate或截断日志文件。在绝大多数 Linux 发行版上这个任务由logrotate承担。只需在/etc/logrotate.d/mediamtx创建一个配置文件内容如下/my/mediamtx/path/mediamtx.log { daily copytruncate rotate 7 compress delaycompress missingok notifempty }各指令含义daily每天轮转一次copytruncate先复制当前文件内容再将其截断进程不需要重启、也不影响 MediaMTX 持续持有的文件描述符适合单写进程的日志文件rotate 7保留 7 份旧日志compress旧日志用 gzip 压缩以节省磁盘delaycompress最新一份旧日志延迟一个轮转周期再压缩便于立即查阅missingok文件不存在时静默跳过不报错notifempty文件为空时不轮转。轮转后旧日志会带上.1、.2、.3……的数字后缀mediamtx.log.1 mediamtx.log.2 mediamtx.log.3 ...如果你把logFile指向了其他路径例如/var/log/mediamtx.log记得同步修改 logrotate 配置文件中的路径并在轮转策略中加入适当的权限与压缩设置。配置热重载与日志器生命周期日志配置并非一成不变MediaMTX 支持配置文件变更热重载日志器也会随重载重建。在 internal/core/core.go 中可以看到检测到配置文件变化后会重新加载配置并重建各组件日志器在 core.go 中通过新建日志器 → 替换 → 关闭旧日志器的方式平滑切换期间旧的 file 句柄会被正确关闭。这意味着你可以在运行中把logLevel从info临时调低到debug排查问题再调回info无需重启进程。小结与排查建议日常运行保持logLevel: info、logDestinations: [stdout]即可需要审计留档时把file目标与 logrotate 组合使用需要集中采集时开启logStructured: true并交给 Loki / Logstash / CloudWatch 等工具消费。排查推拉流异常时把logLevel临时改为debug可看到最详细的事件链路配合 syslog 目标与journalctl SYSLOG_IDENTIFIERmediamtx或 systemd 服务的journalctl -u mediamtx可统一检索。所有日志参数均定义于 internal/conf/conf.go完整的默认值与注释可查看根目录 mediamtx.yml更全面的配置说明见 1-configuration-file.md。【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MediaMTX 日志配置实战日志级别、多目标输出、JSONL 结构化日志与日志轮转【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtxMediaMTX 内置了一套轻量、可扩展的日志系统通过logLevel、logDestinations、logFile、sysLogPrefix、logStructured等配置项即可在不重启编译的前提下完成日志级别控制、stdout / 文件 / syslog 多目标输出、JSONL 结构化日志以及基于 logrotate 的日志轮转。读完本文你将掌握 MediaMTX 日志从级别过滤—目标分发—结构化格式化—轮转归档的完整链路并能直接在生产环境中落地一套可查询、可采集、可归档的日志方案。日志级别用 logLevel 控制输出粒度MediaMTX 提供 4 个日志级别由配置项logLevel指定# Verbosity of the program; available values are error, warn, info, debug. logLevel: info取值含义典型场景error仅输出错误生产环境的最小化输出适合日志量大、只关心故障的场景warn输出警告与错误关注潜在风险但不希望被常规信息刷屏info输出常规信息、警告与错误默认值默认配置记录服务启动、监听端口、连接会话等关键事件debug输出全部日志含调试信息排查问题、分析推拉流细节时使用从源码实现看级别过滤发生在最前端的入口处internal/logger/logger.go 的Log()方法首先执行if level l.Level { return }低于配置级别的事件会被直接丢弃不会进入任何输出目标因此调整logLevel对性能的影响很小。级别常量定义在 internal/logger/level.go 中按Debug → Info → Warn → Error递增logLevel: info即意味着 Info、Warn、Error 三级事件都会被输出。级别字符串到内部枚举的解析由 internal/conf/log_level.go 完成它同时支持 JSON 与环境变量两种反序列化方式非法取值会直接报错invalid log level: xxx。根目录的默认配置文件 mediamtx.yml 中即采用logLevel: info如果你希望控制台安静一些可以改为logLevel: warn或logLevel: error。日志输出目标stdout / file / syslog 可组合logDestinations决定日志写往哪些目标它是一个数组可以同时启用多个目标事件会并发分发到所有已启用的目标# Destinations of log messages; available values are stdout, file and syslog. logDestinations: [file] # If file is in logDestinations, this is the file which will receive the logs. logFile: mediamtx.log默认情况下日志只打印到控制台stdout。可用的目标值在 internal/conf/log_destination.go 中定义并解析三个合法值为stdout、file、syslog在 internal/logger/logger.go 的Initialize()中会按目标类型逐一创建对应的输出处理器stdout 目标写入标准输出、file 目标打开指定文件、syslog 目标连接系统日志服务。目标列表也支持通过环境变量以逗号分隔传入解析逻辑见 internal/conf/log_destinations.go。写入文件logFile当logDestinations包含file时日志会追加写入logFile指定的文件默认mediamtx.log。从 internal/logger/destination_file.go 可以看到文件以O_APPEND|O_CREATE|O_WRONLY模式打开、权限为0644因此进程启动时文件不存在会自动创建且始终以追加方式写入不会覆盖历史日志。日志器内部通过互斥锁串行化写入见logger.go的mutex字段保证多条日志并发产生时不会交错。写入系统日志syslog当logDestinations包含syslog时日志会发给系统日志服务# Destinations of log messages; available values are stdout, file and syslog. logDestinations: [syslog] # If syslog is in logDestinations, use prefix for logs. sysLogPrefix: mediamtxsysLogPrefix指定日志的标识前缀默认mediamtx。从 internal/logger/destination_syslog_other.go 的实现看它调用syslog.New(syslog.LOG_DAEMON, prefix)连接系统 syslogfacility 为 daemon并把四个日志级别分别映射为 syslog 的Debug / Info / Warning / Err方法与 stdout、file 目标不同syslog 目标只发送消息正文——时间戳和级别由 syslog 服务自身负责附加。注意该实现位于带!darwin !windows构建标签的文件中即 Linux 等 Unix 系平台可用Windows 与 macOS 有各自的适配实现。在 systemd 环境下日志会进入 journald可以通过标识符直接查询journalctl SYSLOG_IDENTIFIERmediamtx以 systemd 服务运行时的日志查询如果 MediaMTX 还以系统服务方式运行配置方法见 17-start-on-boot.md则可以借助 systemd 的 unit 名过滤全部日志无需关心sysLogPrefixjournalctl -u mediamtx这种方式会同时带出服务自身的启动、停止、崩溃等 systemd 事件与 MediaMTX 的输出日志排查服务为什么没起来类问题非常高效。结构化日志logStructured 输出 JSONL主流日志采集器Loki、Logstash、CloudWatch、fluentd 等在解析带固定字段的 JSON LinesJSONL时比解析自由文本可靠得多。MediaMTX 通过logStructured开启结构化输出# When destination is stdout or file, emit logs in structured format (JSONL). logStructured: true开启后每条日志是一个单行 JSON 对象形如{timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[RTSP] listener opened on :8554 (TCP/RTSP), :8000 (UDP/RTP), :8001 (UDP/RTCP)} {timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[RTMP] listener opened on :1935} {timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[HLS] listener opened on :8888} {timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[WebRTC] listener opened on :8889 (TCP/HTTP), :8189 (UDP/ICE)} {timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[SRT] listener opened on :8890 (UDP)}每个 JSON 对象包含三个字段timestampRFC3339Nano 格式的时间戳精确到纳秒并含时区偏移由 destination_stdout.go 与 destination_file.go 中的t.Format(time.RFC3339Nano)生成level级别缩写DEB/INF/WAR/ERRmessage经过转义的完整日志消息含[RTSP]、[HLS]之类的协议模块前缀。结构化输出仅对stdout与file两个目标生效配置注释与代码均如此规定syslog 目标天然由系统日志服务结构化因此不受影响。值得注意的是非结构化模式下 stdout / file 输出的是YYYY/MM/DD HH:MM:SS INF message形式的纯文本且 stdout 在连接终端时会自动着色term.IsTerminal检测见 destination_stdout.go而写入文件与结构化模式不会带颜色。日志文件轮转借助 logrotate 归档旧日志MediaMTX 自身不提供内置的日志分割机制官方推荐使用外部工具定期轮转rotate或截断日志文件。在绝大多数 Linux 发行版上这个任务由logrotate承担。只需在/etc/logrotate.d/mediamtx创建一个配置文件内容如下/my/mediamtx/path/mediamtx.log { daily copytruncate rotate 7 compress delaycompress missingok notifempty }各指令含义daily每天轮转一次copytruncate先复制当前文件内容再将其截断进程不需要重启、也不影响 MediaMTX 持续持有的文件描述符适合单写进程的日志文件rotate 7保留 7 份旧日志compress旧日志用 gzip 压缩以节省磁盘delaycompress最新一份旧日志延迟一个轮转周期再压缩便于立即查阅missingok文件不存在时静默跳过不报错notifempty文件为空时不轮转。轮转后旧日志会带上.1、.2、.3……的数字后缀mediamtx.log.1 mediamtx.log.2 mediamtx.log.3 ...如果你把logFile指向了其他路径例如/var/log/mediamtx.log记得同步修改 logrotate 配置文件中的路径并在轮转策略中加入适当的权限与压缩设置。配置热重载与日志器生命周期日志配置并非一成不变MediaMTX 支持配置文件变更热重载日志器也会随重载重建。在 internal/core/core.go 中可以看到检测到配置文件变化后会重新加载配置并重建各组件日志器在 core.go 中通过新建日志器 → 替换 → 关闭旧日志器的方式平滑切换期间旧的 file 句柄会被正确关闭。这意味着你可以在运行中把logLevel从info临时调低到debug排查问题再调回info无需重启进程。小结与排查建议日常运行保持logLevel: info、logDestinations: [stdout]即可需要审计留档时把file目标与 logrotate 组合使用需要集中采集时开启logStructured: true并交给 Loki / Logstash / CloudWatch 等工具消费。排查推拉流异常时把logLevel临时改为debug可看到最详细的事件链路配合 syslog 目标与journalctl SYSLOG_IDENTIFIERmediamtx或 systemd 服务的journalctl -u mediamtx可统一检索。所有日志参数均定义于 internal/conf/conf.go完整的默认值与注释可查看根目录 mediamtx.yml更全面的配置说明见 1-configuration-file.md。【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
