ApsaraVideo VOD:Système de journalisation

Qu'est-ce que LogHub ?

LogHub est le point d'entrée unifié pour toutes les sorties de journal dans le framework PlayerKit. Il s'agit d'une classe utilitaire statique qui offre des fonctionnalités de journalisation cohérentes.

LogHub encapsule l'API native Log d'Android. Il conserve toutes les capacités d'origine et ajoute les fonctionnalités principales suivantes :

Qu'est-ce qu'un écouteur de journal ?

LogHubListener est une interface de rappel qui reçoit les journaux de LogHub. Implémentez cette interface pour personnaliser la manière dont les journaux sont traités. Par exemple :

• Écrivez les journaux dans un fichier afin de les partager avec le support technique lors du dépannage.

• Téléchargez les journaux sur un serveur distant pour une collecte centralisée.

• Affichez les journaux dans l'interface utilisateur pour un panneau de débogage.

Problèmes résolus

• Les journaux sont dispersés dans le code, ce qui rend leur gestion et leur filtrage difficiles.

• Les versions de production doivent désactiver les journaux de débogage, mais aucun commutateur unifié n'existe.

• Aucune prise en charge intégrée des fichiers journaux pour le dépannage.

• Les journaux du SDK Player et les journaux métier sont séparés, ce qui rend l'analyse associative difficile.

Valeur principale

Avantages architecturaux :

• Point d'entrée unifié : Tous les journaux transitent par LogHub, ce qui simplifie la gestion et le contrôle.

• Contrôle flexible : Prend en charge trois niveaux de contrôle : activation globale, activation de la console et filtrage par niveau.

• Extensible : Le mécanisme d'écouteurs prend en charge la gestion personnalisée des journaux, telle que l'écriture dans des fichiers et le reporting à distance.

• Sécurité des threads : La liste des écouteurs utilise CopyOnWriteArrayList pour un accès concurrent sécurisé.

Capacités principales

Niveaux de journal

Classes principales

Stratégie 1 : Sortie directe des journaux

Appelez directement les méthodes statiques de LogHub :

// Output an INFO log
LogHub.i(this, "playVideo", "Start playing video");

// Output a WARN log
LogHub.w(this, "onBuffering", "Buffering. Current progress: ", progress);

// Output an ERROR log
LogHub.e(this, "onError", "Playback failed. Error code: ", errorCode);

// Output an ERROR log with an exception
LogHub.e(this, "onException", throwable, "An exception occurred");

// Output a performance timing log
LogHub.t("loadVideoSource", costTime);

Format du journal :

[Class name] Method name: Message

Suggestion de filtrage Logcat :

package:mine tag:AliPlayerKit

Stratégie 2 : Configuration du niveau de journal

Définissez différents niveaux de journal en fonction de l'environnement d'exécution :

// Development environment: Output all logs
if (BuildConfig.DEBUG) {
    LogHub.setEnableLog(true);
    LogHub.setEnableConsoleLog(true);
    LogHub.setLogLevel(LogLevel.VERBOSE);
}

// Production environment: Output only INFO and above
else {
    LogHub.setEnableLog(true);
    LogHub.setEnableConsoleLog(false);  // Disable console output
    LogHub.setLogLevel(LogLevel.INFO);
}

// Disable all logs (for sensitive scenarios)
LogHub.setEnableLog(false);

Stratégie 3 : Enregistrement d'un écouteur

Personnalisez la gestion des journaux à l'aide d'un écouteur :

// Create a listener
LogHubListener listener = logInfo -> {
    // Process the log
    String formattedLog = logInfo.getFormattedMessage();
    // Write to file, upload to server, etc.
    saveToFile(formattedLog);
};

// Register the listener
LogHub.addListener(listener);

// Remove the listener when no longer needed
LogHub.removeListener(listener);   

Comment implémenter la persistance des journaux ?

Implémentez la journalisation basée sur des fichiers à l'aide de l'interface LogHubListener pour faciliter le dépannage.

1. Créez un écouteur de journal.

   public class FileLogListener implements LogHubListener {
   
       private final ExecutorService mExecutor = Executors.newSingleThreadExecutor();
       private final File mLogFile;
   
       public FileLogListener(Context context) {
           // Log file path
           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) {
           // Write to file asynchronously to avoid blocking the calling thread
           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) {
                   // Ignore write exceptions
               }
           });
       }
   }

2. Enregistrez-le dans votre classe Application.

   public class MyApplication extends Application {
   
       private FileLogListener mFileLogListener;
   
       @Overridepublic void onCreate() {
           super.onCreate();
   
           // Create and register the file log listener
           mFileLogListener = new FileLogListener(this);
           LogHub.addListener(mFileLogListener);
       }
   }

3. Récupérez le fichier journal.

   // Log file path
   File logDir = new File(getExternalFilesDir(null), "logs");
   File[] logFiles = logDir.listFiles();
   
   // Share with technical support for analysis

Exemple de référence : playerkit-examples/example-log-system/FileLogListener.java.

Comment intégrer les journaux du SDK Player ?

Utilisez l'interface IPlayerLogger pour gérer uniformément les journaux du SDK Player.

1. Créez une instance de journaliseur du lecteur.

   // Initialize in Application
   IPlayerLogger playerLogger = new DefaultPlayerLogger(context);
   
   // Enable SDK console logs (enable only for debugging)
   playerLogger.enableConsoleLog(BuildConfig.DEBUG);
   
   // Set SDK log level
   playerLogger.setLogLevel(LogLevel.INFO);

2. Définissez le rappel de journal du SDK.

   playerLogger.setLogCallback((level, message) -> {
       // Handle SDK logs, such as writing to file or reporting remotely
       LogHub.log(level, "PlayerSDK", message);
   });

Comment afficher les journaux dans l'interface utilisateur ?

Utilisez un écouteur pour afficher les journaux en temps réel à l'écran.

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);

        // Create a UI log listener
        mLogListener = logInfo -> runOnUiThread(() -> {
            mTvLogOutput.append(logInfo.getFormattedMessage() + "\n");
        });

        // Register the listener
        LogHub.addListener(mLogListener);
    }

    @Overrideprotected void onDestroy() {
        super.onDestroy();
        // Remove the listener to prevent memory leaks
        LogHub.removeListener(mLogListener);
    }
}

Sélection des niveaux de journal

Configuration de l'environnement de production

public class MyApplication extends Application {

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

        if (BuildConfig.DEBUG) {
            // Development: Detailed logs + console output
            LogHub.setEnableLog(true);
            LogHub.setEnableConsoleLog(true);
            LogHub.setLogLevel(LogLevel.VERBOSE);
        } else {
            // Production: Minimal logs + no console + file persistence
            LogHub.setEnableLog(true);
            LogHub.setEnableConsoleLog(false);  // Disable Logcat output
            LogHub.setLogLevel(LogLevel.INFO);   // Keep only INFO and above
            LogHub.addListener(new FileLogListener(this));
        }
    }
}  

Remarques

Fonctionnalités de l'exemple

Exécution de l'exemple

Dans l'application Demo, sélectionnez l'exemple Log System pour voir les résultats.

Interfaces principales

Méthodes principales de LogHub

Méthodes principales de LogInfo

Segmentation des longs journaux

Logcat limite chaque ligne de journal à environ 4000 caractères. LogHub gère les longs journaux en les segmentant :

private static final int BUFFER_SIZE = 3000;

// Segment and output to Logcatwhile (startIndex < length) {
    int endIndex = Math.min(length, startIndex + BUFFER_SIZE);
    String sub = s.substring(startIndex, endIndex);
    // Output segmented log...
    startIndex = endIndex;
}

Optimisation : Envoyez les journaux complets aux écouteurs. Segmentez uniquement pour la sortie Logcat.

Sécurité des threads

La liste des écouteurs utilise CopyOnWriteArrayList pour garantir la sécurité des threads :

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

Caractéristiques :

• Les opérations de lecture ne nécessitent aucun verrou. Les performances sont élevées.

• Les opérations d'écriture copient un nouveau tableau. Les lectures en cours ne sont pas affectées.

• Idéal pour l'enregistrement et la suppression d'écouteurs, où les lectures sont beaucoup plus nombreuses que les écritures.

Comment filtrer les journaux PlayerKit dans Logcat ?

Utilisez ce filtre :

package:mine tag:AliPlayerKit

Ou filtrez par niveau :

package:mine tag:AliPlayerKit level:info       

Où sont stockés les fichiers journaux de l'environnement de production ?

Chemin par défaut (si vous utilisez l'exemple FileLogListener) :

/sdcard/Android/data/[package name]/files/logs/

Sur quel thread s'exécutent les rappels des écouteurs ?

Les rappels des écouteurs s'exécutent sur le même thread que celui qui émet le journal. Pour traiter les journaux sur le thread d'interface utilisateur, utilisez runOnUiThread() pour changer de thread.

Erreurs courantes

Voici les problèmes les plus fréquemment signalés par les clients. Évitez-les :

@Overridepublic void onLog(@NonNull LogInfo logInfo) {
    // Synchronous file write on main thread blocks the 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) {
    // Write to file asynchronously
    mExecutor.execute(() -> {
        try {
            // File write logic...
        } catch (IOException e) {
            // Ignore
        }
    });
}

@Overrideprotected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // Registered a listener but never removed it
    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();
    // Remove the listener promptlyif (mLogListener != null) {
        LogHub.removeListener(mLogListener);
    }
}

@Overridepublic void onLog(@NonNull LogInfo logInfo) {
    // Unhandled exception. If thrown here, it affects other listeners
    String data = logInfo.getMessage();
    int result = 1 / 0;  // Throws exception
}

@Overridepublic void onLog(@NonNull LogInfo logInfo) {
    try {
        // Handle exceptions inside the listener
        processLog(logInfo);
    } catch (Exception e) {
        // Handle listener-specific exceptions without affecting the logging system
        android.util.Log.e("FileLogListener", "Error processing log", e);
    }
}

Comment déboguer ?

1. Vérifiez l'état d'activation des journaux :

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

2. Consultez la sortie Logcat :

   Filtrez les journaux à l'aide de tag:AliPlayerKit.

3. Vérifiez le nombre d'écouteurs :

   Vous pouvez inspecter le nombre d'écouteurs enregistrés à l'aide de la réflexion (uniquement pour le débogage). Vérifiez que les écouteurs sont correctement enregistrés et supprimés.