MSAL for Android 中的日志记录Logging in MSAL for Android

Microsoft 身份验证库 (MSAL) 应用生成日志消息,这些消息可以用来诊断问题。The Microsoft Authentication Library (MSAL) apps generate log messages that can help diagnose issues. 应用可以通过数行代码配置日志记录,并可对详细程度以及是否记录个人和组织数据进行自定义控制。An app can configure logging with a few lines of code, and have custom control over the level of detail and whether or not personal and organizational data is logged. 建议创建 MSAL 日志记录回调,并提供一种方式来让用户在遇到身份验证问题时提交日志。We recommend you create an MSAL logging callback and provide a way for users to submit logs when they have authentication issues.

日志记录级别Logging levels

MSAL 提供多个日志记录详细级别:MSAL provides several levels of logging detail:

  • 错误:指示出现问题并已生成错误。Error: Indicates something has gone wrong and an error was generated. 用于调试并确定问题。Used for debugging and identifying problems.
  • 警告:不一定会出现错误或故障,只是为了诊断和指出问题。Warning: There hasn't necessarily been an error or failure, but are intended for diagnostics and pinpointing problems.
  • 信息:MSAL 将要记录的事件可为用户提供信息,不一定用于调试。Info: MSAL will log events intended for informational purposes not necessarily intended for debugging.
  • 详细:默认。Verbose: Default. MSAL 将记录库行为的完整详细信息。MSAL logs the full details of library behavior.

个人和组织数据Personal and organizational data

默认情况下,MSAL 记录器不捕获任何高度敏感的个人或组织数据。By default, the MSAL logger doesn't capture any highly sensitive personal or organizational data. 该库提供相关选项,允许你自行决定是否记录个人和组织数据。The library provides the option to enable logging personal and organizational data if you decide to do so.

以下各节将详细介绍应用程序的 MSAL 错误日志记录。The following sections provide more details about MSAL error logging for your application.

使用 Java 的 MSAL for Android 中的日志记录Logging in MSAL for Android using Java

创建应用时通过创建日志记录回调来启用日志记录。Turn logging on at app creation by creating a logging callback. 该回调采用以下参数:The callback takes these parameters:

  • tag 由库传递给回调的字符串。tag is a string passed to the callback by the library. 它与日志条目相关联,可用于对日志记录消息排序。It is associated with the log entry and can be used to sort logging messages.
  • logLevel 用于确定所需的日志记录级别。logLevel enables you to decide which level of logging you want. 支持的日志级别为:ErrorWarningInfoVerboseThe supported log levels are: Error, Warning, Info, and Verbose.
  • message 是日志条目的内容。message is the content of the log entry.
  • containsPII 指定是要记录包含个人数据还是组织数据的消息。containsPII specifies whether messages containing personal data, or organizational data are logged. 默认情况下,此项设置为 false,不允许应用程序记录个人数据。By default, this is set to false, so that your application doesn't log personal data. 如果 containsPIItrue,则此方法会接收消息两次:第一次时 containsPII 参数设置为 falsemessage 不包含个人数据;第二次时 containsPii 参数设置为 true,消息可能包含个人数据。If containsPII is true, this method will receive the messages twice: once with the containsPII parameter set to false and the message without personal data, and a second time with the containsPii parameter set to true and the message might contain personal data. 在某些情况下(消息不含个人数据),消息是相同的。In some cases (when the message does not contain personal data), the message will be the same.
private StringBuilder mLogs;

mLogs = new StringBuilder();
Logger.getInstance().setExternalLogger(new ILoggerCallback()
{
   @Override
   public void log(String tag, Logger.LogLevel logLevel, String message, boolean containsPII)
   {
      mLogs.append(message).append('\n');
   }
});

默认情况下,MSAL 记录器将不会捕获任何个人身份信息或组织身份信息。By default, the MSAL logger will not capture any personal identifiable information or organizational identifiable information. 若要记录个人身份信息或组织身份信息:To enable the logging of personal identifiable information or organizational identifiable information:

Logger.getInstance().setEnablePII(true);

若要禁止记录个人数据和组织数据:To disable logging personal data and organization data:

Logger.getInstance().setEnablePII(false);

默认情况下,将禁用记录到 logcat。By default logging to logcat is disabled. 若要启用:To enable:

Logger.getInstance().setEnableLogcatLog(true);

后续步骤Next steps

有关更多代码示例,请参阅 Microsoft 标识平台代码示例For more code samples, refer to Microsoft identity platform code samples.