ApsaraVideo VOD:ログシステム

概念

LogHub とは

LogHub は、AliPlayerKit のすべてのログ出力に対する統一されたエントリーポイントです。シングルトンパターンで設計されています。LogHub は、ネイティブの iOS ログ API である NSLog をカプセル化し、以下のコア機能を追加します：

ログオブザーバーとは

ログオブザーバー (LogObserver) は、LogHub からログを受信するためのコールバックプロトコルです。このプロトコルを実装することで、ログの処理方法をカスタマイズできます。例：

• テクニカルサポートチームがトラブルシューティングに使用できるよう、ログをファイルに書き込みます。

• リモートログ収集を有効にするために、ログをリモートサーバーにアップロードします。

• デバッグパネルを作成するために、ログを UI に表示します。

ハイブリッドスレッドモデル

LogHub はハイブリッドスレッドモデルを使用します：

機能

コア機能

コアコンポーネント

使用方法

基本的な使用方法：グローバルクイック設定

推奨される AliPlayerKit のクラスメソッドを使用して、ログシステムをすばやく設定できます：

// AppDelegate で、セットアップ後に設定します
[AliPlayerKit setup];

// ログレベルを設定します
[AliPlayerKit setLogLevel:LogLevelVerbose];

// コンソールログを有効または無効にします
[AliPlayerKit enableConsoleLog:YES];

基本的な使用方法：ログ出力

SLOG シリーズのヘルパーマクロを使用して、レベルごとにログを出力できます。これらのマクロは、ソースファイル名と行番号を自動的に取得します：

#import <AliPlayerKit/LogMacros.h>

// さまざまなレベルでログを出力します (__FILE_NAME__ と __LINE__ を自動的に取得します)
SLOGV(@"viewDidLoad called");
SLOGD(@"Configure player: videoId=%@", videoId);
SLOGI(@"Start playing video: %@", videoTitle);
SLOGW(@"Buffering, current progress: %.1f%%", progress * 100);
SLOGE(@"Playback failed, error code: %ld", (long)errorCode);

ヘルパーマクロの一覧：

LogHub のインスタンスメソッドを直接呼び出し、タグを手動で指定することもできます：

// タグを使用してログの出力元を識別します
[[LogHub sharedHub] i:@"PlayerVC" msg:@"Start playback"];
[[LogHub sharedHub] e:@"MediaPlayer" msg:@"Playback failed" 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 プロトコルを実装することで、ログ処理をカスタマイズできます：

// ファイルログオブザーバーを作成して登録します
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 を更新するには、メインスレッドにディスパッチしてください。
- (void)onLog:(LogInfo *)logInfo;

@end

LogInfo データモデル

整形後の出力形式：

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

エラーがある場合は、さらに1行が追記されます：

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 プロトコル