ApsaraVideo VOD：日誌系統

什麼是 LogHub？

LogHub 是 PlayerKit 架構中所有日誌輸出的統一入口，是一個靜態工具類，提供統一的日誌輸出功能。

它封裝了 Android 原生 Log API，在保留原有功能的基礎上，增加了以下核心能力：

什麼是日誌監聽器？

日誌監聽器 (LogHubListener) 是用於接收 LogHub 輸出日誌的回調介面。通過實現該介面，可以自訂日誌的處理方式，例如：

• 將日誌寫入檔案，便於問題排查時提供給支援人員團隊

• 將日誌上傳到遠程伺服器，實現遠程日誌收集

• 在 UI 上展示日誌，用於調試面板

解決問題

• 日誌分散，難以統一管理和過濾。

• 發布版本需要關閉調試日誌，缺乏統一開關。

• 問題排查時缺乏記錄檔支援。

• 播放器 SDK 日誌與業務日誌分離，難以關聯分析。

核心價值

架構優勢：

• 統一入口：所有日誌通過 LogHub 統一輸出，便於管理和控制。

• 靈活控制：支援全域開關、控制台開關、層級過濾三重控制。

• 可擴充：通過監聽器機制支援自訂Tlog，如檔案寫入、遠程上報。

• 安全執行緒：監聽器列表使用 CopyOnWriteArrayList，支援多安全執行緒訪問。

核心能力

記錄層級

核心類

策略一：直接輸出日誌

最簡單的使用方式，直接調用 LogHub 的靜態方法輸出日誌：

// 輸出 INFO 層級日誌
LogHub.i(this, "playVideo", "開始播放視頻");

// 輸出 WARN 層級日誌
LogHub.w(this, "onBuffering", "緩衝中，當前進度: ", progress);

// 輸出 ERROR 層級日誌
LogHub.e(this, "onError", "播放失敗，錯誤碼: ", errorCode);

// 輸出帶異常的 ERROR 日誌
LogHub.e(this, "onException", throwable, "發生異常");

// 輸出效能時間日誌
LogHub.t("loadVideoSource", costTime);

日誌格式說明：

[類名] 方法名: 訊息內容

Logcat 過濾建議：

package:mine tag:AliPlayerKit

策略二：配置記錄層級

根據運行環境配置不同的記錄層級：

// 開發環境：輸出所有日誌
if (BuildConfig.DEBUG) {
    LogHub.setEnableLog(true);
    LogHub.setEnableConsoleLog(true);
    LogHub.setLogLevel(LogLevel.VERBOSE);
}

// 生產環境：只輸出 INFO 及以上層級
else {
    LogHub.setEnableLog(true);
    LogHub.setEnableConsoleLog(false);  // 關閉控制台輸出
    LogHub.setLogLevel(LogLevel.INFO);
}

// 完全關閉日誌（敏感情境）
LogHub.setEnableLog(false);

策略三：註冊監聽器

通過監聽器實現日誌自訂處理：

// 建立監聽器
LogHubListener listener = logInfo -> {
    // 處理日誌資訊
    String formattedLog = logInfo.getFormattedMessage();
    // 寫入檔案、上傳伺服器等
    saveToFile(formattedLog);
};

// 註冊監聽器
LogHub.addListener(listener);

// 移除監聽器（不再需要時）
LogHub.removeListener(listener);   

如何?日誌持久化？

通過 LogHubListener 介面實現記錄檔寫入，便於問題排查。

1. 建立日誌監聽器。

   public class FileLogListener implements LogHubListener {
   
       private final ExecutorService mExecutor = Executors.newSingleThreadExecutor();
       private final File mLogFile;
   
       public FileLogListener(Context context) {
           // 記錄檔路徑
           File logDir = new File(context.getExternalFilesDir(null), "logs");
           if (!logDir.exists()) {
               logDir.mkdirs();
           }
           mLogFile = new File(logDir, "player_" + getDateStr() + ".log");
       }
   
       @Overridepublic void onLog(@NonNull LogInfo logInfo) {
           // 非同步寫入檔案，避免阻塞調用線程
           mExecutor.execute(() -> {
               try {
                   String log = logInfo.getFormattedMessage() + "\n";
                   FileOutputStream fos = new FileOutputStream(mLogFile, true);
                   fos.write(log.getBytes(StandardCharsets.UTF_8));
                   fos.close();
               } catch (IOException e) {
                   // 忽略寫入異常
               }
           });
       }
   }

2. 在Application中註冊。

   public class MyApplication extends Application {
   
       private FileLogListener mFileLogListener;
   
       @Overridepublic void onCreate() {
           super.onCreate();
   
           // 建立並註冊檔案日誌監聽器
           mFileLogListener = new FileLogListener(this);
           LogHub.addListener(mFileLogListener);
       }
   }

3. 擷取記錄檔。

   // 記錄檔路徑
   File logDir = new File(getExternalFilesDir(null), "logs");
   File[] logFiles = logDir.listFiles();
   
   // 提供給支援人員團隊進行分析

樣本參考：playerkit-examples/example-log-system/FileLogListener.java。

如何整合播放器 SDK 日誌？

通過IPlayerLogger介面統一管理播放器 SDK 的日誌輸出。

1. 建立播放器日誌執行個體。

   // 在 Application 中初始化
   IPlayerLogger playerLogger = new DefaultPlayerLogger(context);
   
   // 啟用 SDK 控制台日誌（調試時開啟）
   playerLogger.enableConsoleLog(BuildConfig.DEBUG);
   
   // 設定 SDK 記錄層級
   playerLogger.setLogLevel(LogLevel.INFO);

2. 設定 SDK 日誌回調。

   playerLogger.setLogCallback((level, message) -> {
       // 處理 SDK 日誌，如寫入檔案、上報等
       LogHub.log(level, "PlayerSDK", message);
   });

如何在 UI 上展示日誌？

通過監聽器將日誌即時展示在介面上。

public class LogPanelActivity extends AppCompatActivity {

    private TextView mTvLogOutput;
    private LogHubListener mLogListener;

    @Overrideprotected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_log_panel);

        mTvLogOutput = findViewById(R.id.tv_log_output);

        // 建立 UI 日誌監聽器
        mLogListener = logInfo -> runOnUiThread(() -> {
            mTvLogOutput.append(logInfo.getFormattedMessage() + "\n");
        });

        // 註冊監聽器
        LogHub.addListener(mLogListener);
    }

    @Overrideprotected void onDestroy() {
        super.onDestroy();
        // 移除監聽器，避免記憶體流失
        LogHub.removeListener(mLogListener);
    }
}

記錄層級選擇

生產環境配置

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        if (BuildConfig.DEBUG) {
            // 開發環境：詳細日誌 + 控制台輸出
            LogHub.setEnableLog(true);
            LogHub.setEnableConsoleLog(true);
            LogHub.setLogLevel(LogLevel.VERBOSE);
        } else {
            // 生產環境：精簡日誌 + 關閉控制台 + 檔案持久化
            LogHub.setEnableLog(true);
            LogHub.setEnableConsoleLog(false);  // 關閉 Logcat 輸出
            LogHub.setLogLevel(LogLevel.INFO);   // 只保留 INFO 及以上
            LogHub.addListener(new FileLogListener(this));
        }
    }
}  

注意事項

樣本功能

運行樣本

在 Demo App 中選擇 Log System 樣本查看效果。

核心介面

LogHub 主要方法

LogInfo 主要方法

長日誌分段機制

Logcat 單條日誌有長度限制（約 4000 字元），LogHub 通過分段機制處理超長日誌：

private static final int BUFFER_SIZE = 3000;

// 分段輸出到 Logcatwhile (startIndex < length) {
    int endIndex = Math.min(length, startIndex + BUFFER_SIZE);
    String sub = s.substring(startIndex, endIndex);
    // 輸出分段日誌...
    startIndex = endIndex;
}

最佳化點：對於監聽器，發送完整的日誌內容；對於 Logcat，進行分段輸出。

安全執行緒機制

監聽器列表使用 CopyOnWriteArrayList，確保多安全執行緒：

private static final List<LogHubListener> sListeners = new CopyOnWriteArrayList<>();

特點：

• 讀操作無鎖，效能高。

• 寫操作複製新數組，不影響進行中的讀操作。

• 適合讀多寫少的監聽器註冊/移除情境。

如何在 Logcat 中過濾 PlayerKit 日誌？

使用以下過濾條件：

package:mine tag:AliPlayerKit

或者按層級過濾：

package:mine tag:AliPlayerKit level:info       

生產環境記錄檔在哪裡？

預設路徑（如果使用 FileLogListener 樣本）：

/sdcard/Android/data/[包名]/files/logs/

監聽器回調在哪個線程？

監聽器回調在日誌輸出的調用線程執行。如果需要在 UI 線程處理，請使用 runOnUiThread() 切換線程。

高頻錯誤錯例

以下是客戶回函中最常導致問題的情況，請務必避免：

@Overridepublic void onLog(@NonNull LogInfo logInfo) {
    // 在主線程同步寫檔案，會阻塞 UItry {
        FileOutputStream fos = new FileOutputStream(mLogFile, true);
        fos.write(logInfo.getFormattedMessage().getBytes());
        fos.close();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

private final ExecutorService mExecutor = Executors.newSingleThreadExecutor();

@Overridepublic void onLog(@NonNull LogInfo logInfo) {
    // 非同步寫入檔案
    mExecutor.execute(() -> {
        try {
            // 檔案寫入邏輯...
        } catch (IOException e) {
            // 忽略
        }
    });
}

@Overrideprotected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // 註冊了監聽器但從未移除
    LogHub.addListener(logInfo -> {
        mTvLogOutput.append(logInfo.getMessage());
    });
}

private LogHubListener mLogListener;

@Overrideprotected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    mLogListener = logInfo -> runOnUiThread(() -> {
        mTvLogOutput.append(logInfo.getMessage());
    });
    LogHub.addListener(mLogListener);
}

@Overrideprotected void onDestroy() {
    super.onDestroy();
    // 及時移除監聽器if (mLogListener != null) {
        LogHub.removeListener(mLogListener);
    }
}

@Overridepublic void onLog(@NonNull LogInfo logInfo) {
    // 未處理異常，如果此處拋出異常會影響其他監聽器
    String data = logInfo.getMessage();
    int result = 1 / 0;  // 拋出異常
}

@Overridepublic void onLog(@NonNull LogInfo logInfo) {
    try {
        // 在監聽器內部處理異常
        processLog(logInfo);
    } catch (Exception e) {
        // 監聽器自身的異常處理，不影響日誌系統
        android.util.Log.e("FileLogListener", "Error processing log", e);
    }
}

如何調試？

1. 檢查日誌開關狀態：

   boolean enabled = LogHub.isLogEnabled();
   boolean consoleEnabled = LogHub.isConsoleLogEnabled();
   int level = LogHub.getLogLevel();

2. 查看 Logcat 輸出：

   使用 tag:AliPlayerKit 過濾查看日誌輸出。

3. 檢查監聽器數量：

   日誌系統的監聽器數量可通過反射查看（調試用），確保監聽器正確註冊和移除。