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

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.

适用于 Python 的 MSAL 日志记录MSAL for Python logging

MSAL for Python 中的日志记录利用 Python 标准库中的日志记录模块Logging in MSAL for Python leverages the logging module in the Python standard library. 可按如下所示配置 MSAL 日志记录(并在 username_password_sample 中查看其运作方式):You can configure MSAL logging as follows (and see it in action in the username_password_sample):

为所有模块启用调试日志记录Enable debug logging for all modules

默认已禁用任何 Python 脚本中的日志记录。By default, the logging in any Python script is turned off. 如果要为脚本中的所有 Python 模块启用详细日志记录,请使用 logging.basicConfig 和级别 logging.DEBUGIf you want to enable verbose logging for all Python modules in your script, use logging.basicConfig with a level of logging.DEBUG:

import logging

logging.basicConfig(level=logging.DEBUG)

这会将提供给日志记录模块的所有日志消息都打印到标准输出。This will print all log messages given to the logging module to the standard output.

配置 MSAL 日志记录级别Configure MSAL logging level

可以通过将 logging.getLogger() 方法与记录器名称 "msal" 一起使用来配置 MSAL for Python 日志提供程序的日志记录级别:You can configure the logging level of the MSAL for Python log provider by using the logging.getLogger() method with the logger name "msal":

import logging

logging.getLogger("msal").setLevel(logging.WARN)

使用 Azure App Insights 配置 MSAL 日志记录Configure MSAL logging with Azure App Insights

Python 日志会提供给日志处理程序(默认情况下为 StreamHandler)。Python logs are given to a log handler, which by default is the StreamHandler. 若要将 MSAL 日志发送到带有检测密钥的 Application Insights,请使用 AzureLogHandler 库提供的 opencensus-ext-azureTo send MSAL logs to an Application Insights with an Instrumentation Key, use the AzureLogHandler provided by the opencensus-ext-azure library.

若要安装 opencensus-ext-azure,请将 opencensus-ext-azure 包从 PyPI 添加到依赖项或进行 pip 安装:To install, opencensus-ext-azure add the opencensus-ext-azure package from PyPI to your dependencies or pip install:

pip install opencensus-ext-azure

然后将 "msal" 日志提供程序的默认处理程序更改为 AzureLogHandler 的实例,其检测密钥在 APP_INSIGHTS_KEY 环境变量中设置:Then change the default handler of the "msal" log provider to an instance of AzureLogHandler with an instrumentation key set in the APP_INSIGHTS_KEY environment variable:

import logging
import os

from opencensus.ext.azure.log_exporter import AzureLogHandler

APP_INSIGHTS_KEY = os.getenv('APP_INSIGHTS_KEY')

logging.getLogger("msal").addHandler(AzureLogHandler(connection_string='InstrumentationKey={0}'.format(APP_INSIGHTS_KEY))

Python 中的个人和组织数据Personal and organizational data in Python

适用于 Python 的 MSAL 不会记录个人数据或组织数据。MSAL for Python does not log personal data or organizational data. 没有任何属性可用于启用或者禁用个人或组织数据的日志记录。There is no property to turn personal or organization data logging on or off.

你可以使用标准的 Python 日志记录来记录所需的任何内容,但需要责任安全处理敏感数据并遵守法规要求。You can use standard Python logging to log whatever you want, but you are responsible for safely handling sensitive data and following regulatory requirements.

有关 Python 中的日志记录的详细信息,请参阅 Python 的日志记录:操作指南For more information about logging in Python, please refer to Python's Logging: how-to.

后续步骤Next steps

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