播放器 SDK 提供本地调试日志和远程日志回捞能力。本地调试用于开发阶段实时查看 Logcat，日志回捞用于根据服务端任务上传设备上指定时间范围内的 SDK 日志，便于排查问题。

日志获取最佳实践 #

自 TTSDK 1.52.1 版本起，播放器 SDK 升级了日志回捞能力。您可以根据应用所处阶段选择以下三种方案，灰度发布阶段强烈建议接入方案二，便于在收到用户反馈后获取问题发生时的日志。

方案一：通过日志回调自行收集日志 #

适用于开发、内测阶段。您可以接入 SDK 的日志回调接口，自行将日志写入文件，并通过自有日志回捞平台收集日志。遇到疑似 SDK 问题时，将日志提供给火山引擎技术支持团队分析。

此方案需要您自行实现日志文件写入和回捞功能。

方案二：主动开启本地日志记录，由火山引擎回捞（推荐） #

适用于灰度发布阶段。您可以通过 SDK 日志配置接口开启日志实时写入本地磁盘。收到用户反馈后，向火山引擎技术支持团队提供问题设备 ID。经您允许后，火山引擎通过自身的日志回捞平台获取并分析日志。

客户端持续写入日志可能带来一定的性能开销。为降低开销，SDK 先将日志写入内存映射文件（mmap），再异步落盘，避免频繁同步磁盘 I/O，对播放器性能的影响较小。

方案三：由火山引擎针对问题设备下发配置 #

适用于应用全量运行阶段。收到用户反馈后，您可以向火山引擎技术支持团队提供问题设备 ID。经您允许后，火山引擎针对该设备下发配置，开启本地日志记录和回捞轮询，并通过自身的日志回捞平台获取并分析日志。

配置下发且设备使用应用后，日志记录和回捞才会生效，因此存在一定延迟，问题也可能不再复现，导致无法获取问题发生时的日志。

从旧版本升级 #

TTSDK 1.52.1 及以上版本支持通过 LogConfig 统一接入日志回捞。原有 Logcat 和日志监听接口继续保留，与日志回捞相互独立。

升级到 TTSDK 1.52.1 后，原有本地调试和日志监听接口无需迁移。如需远程日志回捞，在原有 Env.start() 初始化配置中增加 LogConfig 即可。

开启日志调试 #

初始化播放器 SDK 之前，建议您先开启日志，便于调试和排查问题。

示例代码如下：

VodSDK.openAllVodLog();

// 开启 ttsdk 模块日志
TTVideoLog.turnOn(TTVideoLog.LOG_DEBUG, 1);
// 开启 CacheModule 模块日志
CmLog.turnLogLevel(CmLog.LogLevel.D, true);
// 开启 Engine 模块日志
TTVideoEngineLog.turnOn(TTVideoEngineLog.LOG_DEBUG, 1);
// 开启数据加载模块日志
AVMDLLog.turnOn(AVMDLLog.LOG_DEBUG, 1);
// 开启 License 模块日志
LicenseManager.turnOnLogcat(true);

输出日志到 Logcat #

通过日志监听器可以获取实时日志。以下示例将日志输出到 Logcat；如果采用方案一，请在回调中接入您自己的日志文件写入和回捞逻辑。

开启日志后，参考以下步骤输出特定级别的日志到 Logcat：

1. （可选）设置日志级别：默认情况下，SDK 输出 LOG_INFO、LOG_WARN、LOG_ERROR 和 LOG_KILL 四个层级的日志。在开发和调试阶段，为了更高效地排查问题，建议您额外设置输出 LOG_DEBUG 级别的日志以获取更详尽的信息。

   TTVideoEngineLog.setLogNotifyLevel(TTVideoEngineLog.LOG_DEBUG, 1);
   

2. （必须）设置日志输出监听器：建议在 Application 类的 onCreate 方法中或其他执行 SDK 初始化逻辑的早期阶段设置日志监听器，以确保能捕获从 SDK 初始化开始的全部日志。以下示例代码会将 Engine 生成的日志打印到 Android 的 Logcat。

   // 将 Engine 日志输出到 Logcat
   TTVideoEngineLog.setListener(new TTVideoEngineLogListener() {
       @Override
       public void consoleLog(String log) {
           Log.d("TTVideoEngineLog", log); // 使用 Log.d 打印到 Logcat
       }
   });
   

开启日志回捞 #

TTSDK 1.52.1 及以上版本支持此功能。在首次调用 Env.start() 前创建 LogConfig，并通过 Config.Builder.setLogConfig() 传入日志配置。

import com.pandora.common.env.Env;
import com.pandora.common.env.config.Config;
import com.pandora.common.env.config.LogConfig;

Context appContext = context.getApplicationContext();

LogConfig logConfig = new LogConfig.Builder(appContext)
        .setEnable(true)
        .build();

Config config = new Config.Builder()
        .setApplicationContext(appContext)
        .setAppID(appId)
        .setAppName(appName)
        .setAppVersion(appVersion)
        .setAppChannel(appChannel)
        .setAppRegion(appRegion)
        .setLicenseUri(licenseUri)
        .setLogConfig(logConfig)
        .build();

Env.start(config);

setEnable(true) 同时开启本地日志文件记录和服务端任务查询，setEnable(false) 同时关闭两者。开启后，SDK 先保存本地日志，仅在服务端下发匹配当前设备和时间范围的任务时上传日志。因此，开启日志回捞后未立即上传属于正常现象。

Android 日志回捞范围包括 Engine、Player、MDL 和 Playlist Cache，无需分别注册各模块的日志回捞回调。

可选配置 #

如果仅使用默认配置，除 setEnable(true) 外无需设置其他参数。您也可以按需设置设备标识、日志路径、容量、保留时间和日志级别。

LogConfig logConfig = new LogConfig.Builder(appContext)
        .setEnable(true)
        .setDeviceID(deviceId)
        .setLogPath(logRootPath)
        .setMaxLogSizeM(100)
        .setSingleLogSizeM(2)
        .setLogExpireTimeS(7 * 24 * 60 * 60)
        .setLogLevel(LogConfig.LogLevel.Debug)
        .build();

验证日志回捞 #

1. 启动应用并完成一次视频播放。
2. 确认应用的 files 目录下已生成 VOD 日志文件；如果设置了自定义日志路径，请检查对应目录。
3. 向火山引擎技术支持团队提供当前设备 DID 和问题发生的时间范围，协助创建日志回捞任务。
4. 确认客户端查询到任务并完成日志上传。
5. 获取回捞日志，确认包含 Engine、Player、MDL 和 Cache 日志。

注意事项 #

• 标准 TTSDK AAR 已携带所需的 consumer rules，无需额外添加 JNI keep 规则。
• 点播和直播的日志文件与上传任务相互独立。同进程共存时，少量共享播放器内核日志可能同时出现在 VOD 日志中，但不会影响播放。