ApsaraVideo VOD:ロギングシステム

LogHub とは

LogHub は、PlayerKit フレームワークにおけるすべてのログ出力のための統一エントリポイントです。一貫したロギング機能を提供する静的なユーティリティクラスです。

LogHub は Android のネイティブ Log API をラップしています。元の機能をすべて保持しつつ、以下のコア機能を追加しています。

ログリスナーとは

LogHubListener は、LogHub からログを受信するコールバックインターフェイスです。このインターフェイスを実装することで、ログの処理方法をカスタマイズできます。例：

• トラブルシューティング中にテクニカルサポートと共有するために、ログをファイルに書き込みます。

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

• デバッグパネル用に、ログを UI に表示します。

解決される課題

• ログがコードベース全体に散在しており、管理やフィルタリングが困難です。

• リリースビルドではデバッグログを無効にする必要がありますが、統一された切り替え機能が存在しません。

• トラブルシューティングのためにログファイルを扱う組み込みサポートがありません。

• プレーヤー SDK のログとビジネスログが分離しており、関連付けた分析が困難です。

コアバリュー

アーキテクチャの利点：

• エントリポイントの統一：すべてのログが LogHub を通過するため、管理と制御が簡素化されます。

• 柔軟な制御：グローバルな有効/無効化、コンソールの有効/無効化、レベルフィルタリングの3段階の制御をサポートします。

• 拡張性：リスナーメカニズムにより、ファイルへの書き込みやリモートレポートなどのカスタムログ処理をサポートします。

• スレッドセーフ：リスナーリストは CopyOnWriteArrayList を使用しており、安全に同時アクセスできます。

コア機能

ログレベル

コアクラス

戦略 1：直接的なログ出力

LogHub の静的メソッドを直接呼び出すことができます。

// INFO ログを出力
LogHub.i(this, "playVideo", "Start playing video");

// WARN ログを出力
LogHub.w(this, "onBuffering", "Buffering. Current progress: ", progress);

// ERROR ログを出力
LogHub.e(this, "onError", "Playback failed. Error code: ", errorCode);

// 例外を含む ERROR ログを出力
LogHub.e(this, "onException", throwable, "An exception occurred");

// パフォーマンスタイミングログを出力
LogHub.t("loadVideoSource", costTime);

ログ形式：

[クラス名] メソッド名：メッセージ

Logcat でのフィルタリングの推奨：

package:mine tag:AliPlayerKit

戦略 2：ログレベルの設定

実行環境に基づいて異なるログレベルを設定できます。

// 開発環境：すべてのログを出力
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);

戦略 3：リスナーの登録

リスナーを使用してログ処理をカスタマイズできます。

// リスナーを作成
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));
        }
    }
}  

注意事項

サンプル機能

サンプルの実行

デモアプリで Log System のサンプルを選択すると、結果を確認できます。

コアインターフェイス

LogHub の主要なメソッド

LogInfo の主要なメソッド

長文ログの分割メカニズム

Logcat は各ログ行を約 4000 文字に制限しています。LogHub は長文ログを分割して処理します。

private static final int BUFFER_SIZE = 3000;

// Logcat に分割して出力
while (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/[package name]/files/logs/

リスナーのコールバックはどのスレッドで実行されますか？

リスナーのコールバックは、ログを出力したスレッドと同じスレッドで実行されます。UI スレッドでログを処理するには、runOnUiThread() を使用してスレッドを切り替えます。

よくある間違い

以下は、よく報告される間違いです。これらを避けるようにしてください。

@Overridepublic void onLog(@NonNull LogInfo logInfo) {
    // メインスレッドでの同期的なファイル書き込みが UI をブロック
    try {
        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. リスナーの数を確認します：

   リフレクションを使用して登録されているリスナーの数を確認できます (デバッグ専用)。リスナーが正しく登録および削除されていることを確認します。