MSAL for iOS/macOS 中的日志记录Logging in MSAL for iOS/macOS

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.

适用于 iOS 和 macOS 的 MSAL 日志记录 - ObjCMSAL for iOS and macOS logging-ObjC

设置一个回调来捕获 MSAL 日志记录,并将其合并到自己应用程序的日志记录中。Set a callback to capture MSAL logging and incorporate it in your own application's logging. 回调的签名如下所示:The signature for the callback looks like this:

/*!
    The LogCallback block for the MSAL logger
 
    @param  level           The level of the log message
    @param  message         The message being logged
    @param  containsPII     If the message might contain Personally Identifiable Information (PII)
                            this will be true. Log messages possibly containing PII will not be
                            sent to the callback unless PIllLoggingEnabled is set to YES on the
                            logger.

 */
typedef void (^MSALLogCallback)(MSALLogLevel level, NSString *message, BOOL containsPII);

例如:For example:

[MSALGlobalConfig.loggerConfig setLogCallback:^(MSALLogLevel level, NSString *message, BOOL containsPII)
    {
        if (!containsPII)
        {
#if DEBUG
            // IMPORTANT: MSAL logs may contain sensitive information. Never output MSAL logs with NSLog, or print, directly unless you're running your application in debug mode. If you're writing MSAL logs to file, you must store the file securely.
            NSLog(@"MSAL log: %@", message);
#endif
        }
    }];

个人数据Personal data

默认情况下,MSAL 不会捕获或记录任何个人数据。By default, MSAL doesn't capture or log any personal data. 库允许应用开发人员通过 MSALLogger 类中的某个属性启用该功能。The library allows app developers to turn this on through a property in the MSALLogger class. 启用 pii.Enabled 日志记录后,应用负责安全地处理高度敏感的数据并遵守任何法规要求。By turning on pii.Enabled, the app takes responsibility for safely handling highly sensitive data and following regulatory requirements.

// By default, the `MSALLogger` doesn't capture any PII

// PII will be logged
MSALGlobalConfig.loggerConfig.piiEnabled = YES;

// PII will NOT be logged
MSALGlobalConfig.loggerConfig.piiEnabled = NO;

日志记录级别Logging levels

若要在使用适用于 iOS 和 macOS 的 MSAL 进行日志记录时设置日志记录级别,请使用以下值之一:To set the logging level when you log using MSAL for iOS and macOS, use one of the following values:

LevelLevel 说明Description
MSALLogLevelNothing 禁用所有日志记录Disable all logging
MSALLogLevelError 默认级别,仅在发生错误时输出信息Default level, prints out information only when errors occur
MSALLogLevelWarning 警告Warnings
MSALLogLevelInfo 库入口点,包含参数和各种密钥链操作Library entry points, with parameters and various keychain operations
MSALLogLevelVerbose API 跟踪API tracing

例如:For example:

MSALGlobalConfig.loggerConfig.logLevel = MSALLogLevelVerbose;

日志消息格式Log message format

MSAL 日志消息的消息部分采用 TID = <thread_id> MSAL <sdk_ver> <OS> <OS_ver> [timestamp - correlation_id] message 格式The message portion of MSAL log messages is in the format of TID = <thread_id> MSAL <sdk_ver> <OS> <OS_ver> [timestamp - correlation_id] message

例如:For example:

TID = 551563 MSAL 0.2.0 iOS Sim 12.0 [2018-09-24 00:36:38 - 36764181-EF53-4E4E-B3E5-16FE362CFC44] acquireToken returning with error: (MSALErrorDomain, -42400) User cancelled the authorization session.

提供关联 ID 和时间戳有助于跟踪问题。Providing correlation IDs and timestamps are helpful for tracking down issues. 时间戳和关联 ID 信息在日志消息中提供。Timestamp and correlation ID information is available in the log message. 只能从 MSAL 日志记录消息中可靠地检索这些信息。The only reliable place to retrieve them is from MSAL logging messages.

后续步骤Next steps

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