dash.js 日志系统完全指南:Log Level 配置、控制台输出与 LOG 事件监听
dash.js 日志系统完全指南:Log Level 配置、控制台输出与 LOG 事件监听
dash.js 内置了一套基于分级(log level)的日志系统,用于在播放过程中向浏览器控制台输出诊断信息,帮助开发者定位 Manifest 解析、分片加载、ABR 切换、DRM 与缓冲等环节的问题。本文以官方文档 docs/site/pages/usage/logging.md 为核心,结合 src/core/Debug.js、src/core/Settings.js 等源码与单元测试,完整讲解日志级别的语义、配置方法、底层实现原理以及如何通过 LOG 事件接管日志输出,让你既能快速上手,也能理解其工作机制。
一、日志系统概述:累积式日志级别
dash.js 的日志级别是累积式(cumulative)的:将日志级别设置为某个值后,该级别及以下所有更低级别的消息都会被输出。例如将日志级别设置为 dashjs.Debug.LOG_LEVEL_WARNING,则所有 warning、error 与 fatal 级别的日志都会被写入控制台,而 info 与 debug 级别的消息则被过滤。
日志级别的官方定义与说明如下(摘自 docs/site/pages/usage/logging.md 中的表格):
| Log level | Numeric value | Description |
|---|---|---|
dashjs.Debug.LOG_LEVEL_NONE |
0 | 浏览器控制台中不写入任何消息 |
dashjs.Debug.LOG_LEVEL_FATAL |
1 | 记录致命错误。当错误导致播放完全失败时,该错误被视为致命错误 |
dashjs.Debug.LOG_LEVEL_ERROR |
2 | 记录错误消息 |
dashjs.Debug.LOG_LEVEL_WARNING |
3 | 记录警告消息 |
dashjs.Debug.LOG_LEVEL_INFO |
4 | 记录信息消息 |
dashjs.Debug.LOG_LEVEL_DEBUG |
5 | 记录所有消息 |
这些常量定义在 src/core/Debug.js 中,作为模块工厂的属性对外暴露:
const LOG_LEVEL_NONE = 0;
const LOG_LEVEL_FATAL = 1;
const LOG_LEVEL_ERROR = 2;
const LOG_LEVEL_WARNING = 3;
const LOG_LEVEL_INFO = 4;
const LOG_LEVEL_DEBUG = 5;
默认日志级别为 dashjs.Debug.LOG_LEVEL_WARNING,这一点可以在 src/core/Settings.js 的 defaultSettings 中确认,也可由单元测试 test/unit/test/core/core.Debug.js 验证。也就是说,在不做任何配置的情况下,dash.js 默认只会输出 warning、error 与 fatal 级别的消息,避免控制台被海量 debug 日志刷屏。
二、如何设置日志级别
2.1 使用 updateSettings 设置
设置日志级别最简单的方式是在创建 player 之后,调用 updateSettings 修改 debug.logLevel:
player.updateSettings({
'debug': {
'logLevel': dashjs.Debug.LOG_LEVEL_INFO
}
});
由于日志级别对应的是数值,也可以直接传入数字:
player.updateSettings({
'debug': {
'logLevel': 4
}
});
两种写法等价,4 即 dashjs.Debug.LOG_LEVEL_INFO。使用常量比裸数字更具可读性,也避免在版本升级时因数值变化造成混淆。
2.2 参考示例
官方在 samples/getting-started/logging.html 中提供了一个完整的可运行示例:页面加载 ../../dist/modern/umd/dash.all.debug.js 构建产物,创建一个播放器实例,并在初始化后立即设置日志级别为 LOG_LEVEL_INFO:
player = dashjs.MediaPlayer().create();
player.initialize(video, url, true);
/* Can be LOG_LEVEL_NONE, LOG_LEVEL_FATAL, LOG_LEVEL_ERROR, LOG_LEVEL_WARNING, LOG_LEVEL_INFO or LOG_LEVEL_DEBUG */
player.updateSettings({
'debug': {
'logLevel': dashjs.Debug.LOG_LEVEL_INFO
}
});
另外,docs/site/pages/usage/settings.md 也以日志级别为例演示了 updateSettings 的通用用法,可见 debug.logLevel 是理解 dash.js 配置体系的最佳入门案例。
2.3 设置时机与生效方式
updateSettings 可以在播放器初始化之前或之后调用。需要特别留意的是:日志级别是一个运行时读取的全局配置,Debug 模块在每次写日志时都会通过 settings.get().debug.logLevel 实时读取当前值(见 src/core/Debug.js),因此修改是即时生效的,不需要重建播放器。
三、源码级解析:日志系统的工作原理
3.1 从 getLogger 到控制台输出
dash.js 内部各模块(如 DashAdapter、DashHandler、StreamController、ManifestLoader 等)通过 Debug 单例工厂的 getLogger(instance) 获取一个带 fatal、error、warn、info、debug 五个方法的 Logger 实例(见 src/core/Debug.js 与 src/core/Logger.js)。在整个源码中,getLogger(...) 被大量调用,例如 src/dash/DashAdapter.js 与 src/dash/DashHandler.js,说明几乎所有核心模块都通过该接口输出日志。
doLog 是最终落地的核心函数(src/core/Debug.js),其执行流程如下:
- 组装消息前缀:若开启时间戳(默认开启),在消息前追加
[自启动以来的毫秒数];若开启调用者名称(默认开启),追加[ClassName],若实例提供getType()还会追加[媒体类型]; - 拼接参数:将调用方传入的所有参数逐一拼接到消息字符串中;
- 过滤输出:仅当
settings.get().debug.logLevel >= level时,才把消息交给对应的控制台函数输出; - 事件分发:若开启了
debug.dispatchEvent,则无论日志级别如何,都会触发Events.LOG事件。
级别与浏览器控制台方法的映射在 setup() 中建立(src/core/Debug.js):
logFn[LOG_LEVEL_FATAL] = getLogFn(window.console.error);
logFn[LOG_LEVEL_ERROR] = getLogFn(window.console.error);
logFn[LOG_LEVEL_WARNING] = getLogFn(window.console.warn);
logFn[LOG_LEVEL_INFO] = getLogFn(window.console.info);
logFn[LOG_LEVEL_DEBUG] = getLogFn(window.console.debug);
即 fatal/error 走 console.error,warning 走 console.warn,info 走 console.info,debug 走 console.debug。这也是为什么把日志级别调到 LOG_LEVEL_DEBUG 后,你会在控制台看到带 [Debug] 前缀的调试信息。
3.2 与 Settings 的联动
debug 相关的完整配置项定义在 src/core/Settings.js,共两个:
logLevel(默认dashjs.Debug.LOG_LEVEL_WARNING):设定日志级别,级别是累积的;dispatchEvent(默认false):设为true后,每当产生日志输出时触发LOG事件;注意该事件的分发不受日志级别限制。
两者共同决定日志系统的行为:前者控制“写不写入控制台”,后者控制“要不要上报到业务代码”。
3.3 单元测试如何验证
test/unit/test/core/core.Debug.js 对日志行为做了系统验证,可作为理解语义的参考:
- 默认值测试:确认默认
logLevel为LOG_LEVEL_WARNING(L28-L31); - 设置测试:确认可通过
settings.update修改日志级别(L33-L38); - 接口测试:确认
getLogger()返回包含debug/info/warn/error/fatal五个方法的对象(L41-L48); - 过滤测试:当级别为
LOG_LEVEL_NONE时,所有级别的消息都不会写入控制台(L50-L65); - 累积语义测试:
LOG_LEVEL_DEBUG下 debug 与 fatal 均会输出;切到LOG_LEVEL_WARNING后 debug 被过滤,而 warn/error 仍输出(L67-L91)。
这些测试直接印证了“累积式”日志级别的行为定义。
四、进阶:通过 LOG 事件接管日志
当默认的控制台输出无法满足需求(例如需要把日志发送到远端服务器、展示在页面调试面板中,或与第三方监控系统对接)时,可以开启 dispatchEvent 并监听 LOG 事件:
player.updateSettings({
'debug': {
'logLevel': dashjs.Debug.LOG_LEVEL_INFO,
'dispatchEvent': true
}
});
player.on(dashjs.MediaPlayer.events.LOG, function (event) {
console.log('dash.js log:', event.message, 'level:', event.level);
// 可在此将日志上报到远端监控系统
});
事件名 'log' 定义在 src/streaming/MediaPlayerEvents.js,由 Debug.doLog 通过事件总线触发(src/core/Debug.js)。事件对象包含两个字段:
| 字段 | 含义 |
|---|---|
message |
格式化后的完整日志消息(含时间戳、调用者类名与消息正文) |
level |
该条日志对应的数值级别(0~5) |
需要强调两点:
dispatchEvent与logLevel是独立的:即使logLevel为LOG_LEVEL_NONE,只要dispatchEvent为true,LOG事件依然会触发(事件分发在级别过滤判断之外,见 src/core/Debug.js 与 src/core/Settings.js 的注释)。因此可以“静默控制台、只收事件”,把日志完全交给业务层处理;- 消息已完成格式化:
event.message是包含[时间戳][类名][类型]前缀的完整字符串,直接可用于展示或上报。
五、调试实践建议
结合日志系统的设计,可以总结出以下实用建议:
- 排查播放问题从
LOG_LEVEL_DEBUG开始:debug 级别会输出所有消息,覆盖 Manifest 加载、分片请求、缓冲与 ABR 决策等关键路径,是定位问题的一手信息来源; - 生产环境保持默认或更严格:默认的
LOG_LEVEL_WARNING已能在控制台保持安静的同时暴露异常;对线上页面可显式设置为LOG_LEVEL_ERROR或LOG_LEVEL_NONE,并通过dispatchEvent: true+LOG事件将错误上报到自有监控平台; - 善用前缀信息:开启(默认开启)的时间戳与类名前缀能帮你快速判断日志来自哪个模块、发生在播放开始后的哪个时刻;
- 注意调试构建:示例页面引用的是
dash.all.debug.js调试构建;不同的构建产物对日志信息的保留程度不同,分析问题时请确认页面加载的是带调试信息的版本。
六、总结
dash.js 的日志系统围绕 Debug 单例(src/core/Debug.js)与 debug 配置段(src/core/Settings.js)构建,核心要点可归纳为:
- 六个累积式日志级别(
NONE=0到DEBUG=5),通过dashjs.Debug.LOG_LEVEL_*常量或数值设置; - 用
player.updateSettings({ debug: { logLevel: ... } })即可在运行时即时切换; - 日志消息带有模块类名、媒体类型与时间戳前缀,并按级别映射到
console.error/warn/info/debug; - 开启
debug.dispatchEvent后,无论级别如何都会触发MediaPlayer.events.LOG事件,便于将日志接入自有监控体系。
掌握了这套配置与原理,你就能在开发与线上排障中高效利用 dash.js 的日志输出,快速定位 MPEG-DASH 播放链路中的各类问题。