ApsaraVideo VOD：日誌系統

概念介紹

什麼是 LogHub？

LogHub 是 AliPlayerKit 中所有日誌輸出的統一入口，採用單例模式設計。它封裝了 iOS 原生日誌 API（NSLog），在保留原有功能的基礎上，增加了以下核心能力：

什麼是日誌觀察者？

日誌觀察者 (LogObserver) 是用於接收 LogHub 輸出日誌的回調協議。通過實現該協議，可以自訂日誌的處理方式，例如：

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

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

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

混合執行緒模式

LogHub 採用混合執行緒模式：

功能特性

核心能力

核心組件

使用方式

基本用法 — 全域快捷配置

通過 AliPlayerKit 類方法快速配置日誌系統（推薦方式）：

// 在 AppDelegate 中，setup 之後配置
[AliPlayerKit setup];

// 設定記錄層級
[AliPlayerKit setLogLevel:LogLevelVerbose];

// 啟用/禁用控制台日誌
[AliPlayerKit enableConsoleLog:YES];

基本用法 — 輸出日誌

使用 SLOG 系列便捷宏輸出各層級日誌，宏會自動捕獲源檔案名稱和行號：

#import <AliPlayerKit/LogMacros.h>

// 輸出各層級日誌（自動捕獲 __FILE_NAME__ 和 __LINE__）
SLOGV(@"viewDidLoad called");
SLOGD(@"配置播放器: videoId=%@", videoId);
SLOGI(@"開始播放視頻: %@", videoTitle);
SLOGW(@"緩衝中，當前進度: %.1f%%", progress * 100);
SLOGE(@"播放失敗，錯誤碼: %ld", (long)errorCode);

便捷宏列表：

也可以直接調用 LogHub 執行個體方法，手動指定 tag：

// 使用 tag 標識日誌來源
[[LogHub sharedHub] i:@"PlayerVC" msg:@"開始播放"];
[[LogHub sharedHub] e:@"MediaPlayer" msg:@"播放失敗" error:error];

基本用法 — 配置記錄層級

通過 LogHub 直接配置日誌屬性：

LogHub *logHub = [LogHub sharedHub];

#ifdef DEBUG
    // 開發環境：詳細日誌 + 控制台輸出
    logHub.logEnabled = YES;
    logHub.consoleLogEnabled = YES;
    logHub.logLevel = LogLevelVerbose;
#else
    // 生產環境：精簡日誌 + 關閉控制台
    logHub.logEnabled = YES;
    logHub.consoleLogEnabled = NO;
    logHub.logLevel = LogLevelInfo;
#endif

三重控制機制：

進階用法 — 註冊日誌觀察者

通過實現 LogObserver 協議自訂Tlog：

// 建立並註冊檔案日誌觀察者
FileLogObserver *fileObserver = [[FileLogObserver alloc] init];
[[LogHub sharedHub] addObserver:fileObserver];

// 移除觀察者（不再需要時）
[[LogHub sharedHub] removeObserver:fileObserver];

進階用法 — 日誌面板

LogPanelSlot 是一個內建的調試插槽，可在播放器視圖中即時展示關鍵日誌資訊：

// 啟用日誌面板（建議僅在調試情境中啟用）
[AliPlayerKit setLogPanelEnabled:YES];

自訂開發

日誌觀察者協議 (LogObserver)

@protocol LogObserver <NSObject>

@required

/// 日誌輸出回調
/// @param logInfo 日誌資訊對象，包含層級、標籤、訊息和時間戳記
/// @warning 回調在後台串列隊列執行，如需更新 UI 請 dispatch 到主線程
- (void)onLog:(LogInfo *)logInfo;

@end

LogInfo資料模型

格式化輸出格式：

2024-04-22 10:30:00.123 I/AliPlayerKit [version] [FileName:line] [threadName] : message

如果存在錯誤，將附加額外一行：

Error: domain=xxx code=xxx userInfo=xxx

自訂檔案日誌觀察者樣本

以下是一個檔案日誌觀察者的完整實現：

@interface MyFileLogObserver : NSObject <LogObserver>
- (instancetype)initWithLogDirectory:(NSString *)directory;
@end

@implementation MyFileLogObserver {
    NSString *_logFilePath;
    dispatch_queue_t _writeQueue;
    NSFileHandle *_fileHandle;
}

- (instancetype)initWithLogDirectory:(NSString *)directory {
    self = [super init];
    if (self) {
        _writeQueue = dispatch_queue_create("com.example.filelog",
                                            DISPATCH_QUEUE_SERIAL);
        [self setupLogFileAtDirectory:directory];
    }
    return self;
}

- (void)setupLogFileAtDirectory:(NSString *)directory {
    NSFileManager *fm = [NSFileManager defaultManager];
    if (![fm fileExistsAtPath:directory]) {
        [fm createDirectoryAtPath:directory
      withIntermediateDirectories:YES
                       attributes:nil
                            error:nil];
    }

    NSDateFormatter *formatter = [[NSDateFormatter alloc] init];
    formatter.dateFormat = @"yyyy-MM-dd";
    NSString *fileName = [NSString stringWithFormat:@"player_%@.log",
                          [formatter stringFromDate:[NSDate date]]];
    _logFilePath = [directory stringByAppendingPathComponent:fileName];

    if (![fm fileExistsAtPath:_logFilePath]) {
        [fm createFileAtPath:_logFilePath contents:nil attributes:nil];
    }
    _fileHandle = [NSFileHandle fileHandleForWritingAtPath:_logFilePath];
    [_fileHandle seekToEndOfFile];
}

#pragma mark - LogObserver

- (void)onLog:(LogInfo *)logInfo {
    NSString *formatted = [logInfo formattedString];

    dispatch_async(_writeQueue, ^{
        NSString *line = [formatted stringByAppendingString:@"\n"];
        NSData *data = [line dataUsingEncoding:NSUTF8StringEncoding];
        @try {
            [self->_fileHandle writeData:data];
        } @catch (NSException *exception) {
            // 忽略寫入異常
        }
    });
}

- (void)dealloc {
    [_fileHandle closeFile];
}

@end

完整整合樣本

// AppDelegate.m
#import <AliPlayerKit/AliPlayerKit.h>

@interface AppDelegate ()
@property (nonatomic, strong) MyFileLogObserver *fileLogObserver;
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 1. 初始化 AliPlayerKit
    [AliPlayerKit setup];

    // 2. 配置日誌系統
#ifdef DEBUG
    [AliPlayerKit setLogLevel:LogLevelVerbose];
    [AliPlayerKit enableConsoleLog:YES];
    // 可選：啟用日誌面板
    [AliPlayerKit setLogPanelEnabled:YES];
#else
    [AliPlayerKit setLogLevel:LogLevelInfo];
    [AliPlayerKit enableConsoleLog:NO];

    // 3. 註冊檔案日誌觀察者（僅生產環境）
    NSString *logDir = [NSSearchPathForDirectoriesInDomains(
        NSDocumentDirectory, NSUserDomainMask, YES).firstObject
        stringByAppendingPathComponent:@"PlayerLogs"];
    self.fileLogObserver = [[MyFileLogObserver alloc] initWithLogDirectory:logDir];
    [[LogHub sharedHub] addObserver:self.fileLogObserver];
#endif

    return YES;
}

@end

最佳實務

環境配置建議

常見錯誤

錯誤 1：觀察者回調中直接更新 UI

// ✗ 錯誤：onLog: 在後台串列隊列執行，直接更新 UI 會崩潰
- (void)onLog:(LogInfo *)logInfo {
    self.logLabel.text = [logInfo formattedString];  // 崩潰！
}

// ✓ 正確：切換到主線程更新 UI
- (void)onLog:(LogInfo *)logInfo {
    NSString *formatted = [logInfo formattedString];
    dispatch_async(dispatch_get_main_queue(), ^{
        self.logLabel.text = formatted;
    });
}

錯誤 2：觀察者中同步阻塞操作

// ✗ 錯誤：在回調中同步寫檔案，阻塞日誌分發隊列
- (void)onLog:(LogInfo *)logInfo {
    NSString *log = [logInfo formattedString];
    [log writeToFile:path atomically:YES encoding:NSUTF8StringEncoding error:nil];
}

// ✓ 正確：非同步寫入檔案
- (void)onLog:(LogInfo *)logInfo {
    NSString *log = [logInfo formattedString];
    dispatch_async(_writeQueue, ^{
        // 非同步寫入...
    });
}

錯誤 3：忘記移除觀察者導致循環參考

// LogHub 弱引用觀察者，不移除不會造成循環參考，但可能在頁面消失後仍收到日誌回調
- (void)viewDidLoad {
    [[LogHub sharedHub] addObserver:self];
}

// ✓ 推薦：在生命週期結束時主動移除
- (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    [[LogHub sharedHub] removeObserver:self];
}

API 速查

記錄層級 (LogLevel)

LogHub 核心 API

AliplayerKit日誌快捷API

SLOG便捷宏

LogInfo屬性

LogObserver 協議