ApsaraVideo VOD:Log system

Concepts

What is LogHub?

LogHub is the unified entry point for all log output in AliPlayerKit. It is designed with the singleton pattern. LogHub encapsulates the native iOS log API, NSLog, and adds the following core features:

What is a log observer?

A log observer (LogObserver) is a callback protocol used to receive logs from LogHub. By implementing this protocol, you can customize how logs are processed. For example:

• Write logs to a file for the technical support team to use for troubleshooting.

• Upload logs to a remote server to enable remote log collection.

• Display logs in the UI to create a debug panel.

Hybrid thread model

LogHub uses a hybrid thread model:

Features

Core features

Core components

Usage

Basic usage: Global quick configuration

You can quickly configure the log system using the recommended AliPlayerKit class methods:

// In AppDelegate, configure after setup
[AliPlayerKit setup];

// Set the log level
[AliPlayerKit setLogLevel:LogLevelVerbose];

// Enable or disable console logs
[AliPlayerKit enableConsoleLog:YES];

Basic usage: Log output

You can use the SLOG series of helper macros to output logs at different levels. These macros automatically capture the source file name and line number:

#import <AliPlayerKit/LogMacros.h>

// Output logs at different levels (automatically captures __FILE_NAME__ and __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);

List of helper macros:

You can also call LogHub instance methods directly and specify a tag manually:

// Use a tag to identify the log source
[[LogHub sharedHub] i:@"PlayerVC" msg:@"Start playback"];
[[LogHub sharedHub] e:@"MediaPlayer" msg:@"Playback failed" error:error];

Basic usage: Configure log levels

You can configure log properties directly through LogHub:

LogHub *logHub = [LogHub sharedHub];

#ifdef DEBUG
    // Development environment: Verbose logs + console output
    logHub.logEnabled = YES;
    logHub.consoleLogEnabled = YES;
    logHub.logLevel = LogLevelVerbose;
#else
    // Production environment: Concise logs + console disabled
    logHub.logEnabled = YES;
    logHub.consoleLogEnabled = NO;
    logHub.logLevel = LogLevelInfo;
#endif

Triple control mechanism:

Advanced usage: Register a log observer

You can customize log processing by implementing the LogObserver protocol:

// Create and register a file log observer
FileLogObserver *fileObserver = [[FileLogObserver alloc] init];
[[LogHub sharedHub] addObserver:fileObserver];

// Remove the observer when it is no longer needed
[[LogHub sharedHub] removeObserver:fileObserver];

Advanced usage: Log panel

LogPanelSlot is a built-in debug slot that displays key log information in real time within the player view:

// Enable the log panel (recommended only for debugging scenarios)
[AliPlayerKit setLogPanelEnabled:YES];

Custom development

LogObserver protocol

@protocol LogObserver <NSObject>

@required

/// Log output callback
/// @param logInfo The log information object, which contains the level, tag, message, and timestamp.
/// @warning This callback is executed in a background serial queue. Dispatch to the main thread to update the UI.
- (void)onLog:(LogInfo *)logInfo;

@end

LogInfo data model

Formatted output format:

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

If an error exists, an extra line is appended:

Error: domain=xxx code=xxx userInfo=xxx

Example: Custom file log observer

The following is a complete implementation of a file log observer:

@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) {
            // Ignore write exceptions
        }
    });
}

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

@end

Example: Full integration

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

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

@implementation AppDelegate

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

    // 1. Initialize AliPlayerKit
    [AliPlayerKit setup];

    // 2. Configure the log system
#ifdef DEBUG
    [AliPlayerKit setLogLevel:LogLevelVerbose];
    [AliPlayerKit enableConsoleLog:YES];
    // Optional: Enable the log panel
    [AliPlayerKit setLogPanelEnabled:YES];
#else
    [AliPlayerKit setLogLevel:LogLevelInfo];
    [AliPlayerKit enableConsoleLog:NO];

    // 3. Register a file log observer (production environment only)
    NSString *logDir = [NSSearchPathForDirectoriesInDomains(
        NSDocumentDirectory, NSUserDomainMask, YES).firstObject
        stringByAppendingPathComponent:@"PlayerLogs"];
    self.fileLogObserver = [[MyFileLogObserver alloc] initWithLogDirectory:logDir];
    [[LogHub sharedHub] addObserver:self.fileLogObserver];
#endif

    return YES;
}

@end

Best practices

Environment configuration recommendations

Common errors

Error 1: Updating the UI directly in the observer callback

// ✗ Incorrect: onLog: is executed in a background serial queue. Updating the UI directly will cause a crash.
- (void)onLog:(LogInfo *)logInfo {
    self.logLabel.text = [logInfo formattedString];  // Crash!
}

// ✓ Correct: Switch to the main thread to update the UI.
- (void)onLog:(LogInfo *)logInfo {
    NSString *formatted = [logInfo formattedString];
    dispatch_async(dispatch_get_main_queue(), ^{
        self.logLabel.text = formatted;
    });
}

Error 2: Synchronous blocking operations in the observer

// ✗ Incorrect: Synchronously writing to a file in the callback blocks the log dispatch queue.
- (void)onLog:(LogInfo *)logInfo {
    NSString *log = [logInfo formattedString];
    [log writeToFile:path atomically:YES encoding:NSUTF8StringEncoding error:nil];
}

// ✓ Correct: Asynchronously write to the file.
- (void)onLog:(LogInfo *)logInfo {
    NSString *log = [logInfo formattedString];
    dispatch_async(_writeQueue, ^{
        // Asynchronous write...
    });
}

Error 3: Forgetting to remove the observer, which causes a circular reference

// ✗ Incorrect: LogHub strongly references the observer. Failure to remove it causes a circular reference.
- (void)viewDidLoad {
    [[LogHub sharedHub] addObserver:self];
    // Never released...
}

// ✓ Correct: Remove the observer at the end of the lifecycle.
- (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    [[LogHub sharedHub] removeObserver:self];
}

API reference

Log levels (LogLevel)

LogHub core API

AliPlayerKit log shortcut API

SLOG helper macros

LogInfo properties

LogObserver protocol