启用日志记录

该库为 Google Ads API 互动提供多功能日志记录功能。您可以捕获：

  • 详细信息： 发送给 API 的完整请求和收到的响应。
  • 简洁摘要： API 互动的概要。

您可以通过以下两种方式控制这些日志记录设置：

  • 客户端库配置： 在该库的特定 配置选项中，使用您的 google-ads.yaml文件或环境变量。
  • 以编程方式使用 Python： 使用 Python 的内置 logging 框架进行直接控制。

通过 google-ads.yaml 进行配置

当 GoogleAdsClient 实例初始化时（例如，当您调用 load_from_storage 时），系统会自动配置日志记录。初始化时，该库会执行以下操作：

例如，您可以向 google-ads.yaml 文件添加 logging 部分：

logging:
  version: 1
  disable_existing_loggers: false
  formatters:
    default_fmt:
      format: '[%(asctime)s - %(levelname)s] %(message).5000s'
      datefmt: '%Y-%m-%d %H:%M:%S'
  handlers:
    default_handler:
      class: logging.StreamHandler
      formatter: default_fmt
  loggers:
    '':
      handlers: [default_handler]
      level: INFO

以编程方式进行配置

当您将该库用作已安装的软件包，并且配置文件中没有 logging 部分时，您可以以编程方式将其日志记录与应用的日志记录设置集成。使用 addHandler 将日志记录处理程序附加到该库的记录器 实例 (google.ads.googleads.client)，并 设置目标日志级别：

import logging
import sys

# Retrieve the library's logger instance.
logger = logging.getLogger("google.ads.googleads.client")

# Direct logs to standard output (stdout).
logger.addHandler(logging.StreamHandler(sys.stdout))

# Set the log level to DEBUG to view detailed messages.
logger.setLevel(logging.DEBUG)

如果您希望将日志发送到标准错误 (stderr)（通常用于出错提示和警告），请将 sys.stderr 传递给 logging.StreamHandler：

import logging
import sys

logger = logging.getLogger("google.ads.googleads.client")
logger.addHandler(logging.StreamHandler(sys.stderr))
logger.setLevel(logging.WARNING)

日志级别

客户端会生成多个严重级别的日志，您可以配置记录器以查看以下部分或全部日志：

级别 成功请求 失败请求
DEBUG 详细日志，其中包含完整的请求和响应对象（采用 JSON 格式）。 详细日志，其中包含完整的请求和异常对象（采用 JSON 格式）。
INFO 简洁摘要，其中包含特定的请求和响应字段。 详细日志，其中包含完整的请求和异常对象（采用 JSON 格式）。
WARNING 无 简洁摘要，其中包含特定的请求信息、异常状态和出错提示。

由于 Python 日志记录框架会忽略严重程度低于配置级别的日志消息，因此将级别设置为 WARNING 时，只会显示失败请求的简洁消息；而将级别设置为 DEBUG 时，则会显示表格中的所有日志类型。

记录到文件

您可以通过 Python 以编程方式将日志写入文件，也可以通过从命令行重定向输出。

在 Python 中记录到文件

如需直接从 Python 将日志写入文件，请将 logging.FileHandler 附加到客户端记录器：

import logging

logger = logging.getLogger("google.ads.googleads.client")
file_handler = logging.FileHandler("google_ads.log")
logger.addHandler(file_handler)
logger.setLevel(logging.INFO)

使用 Shell 重定向输出

从命令行运行示例脚本（如 get_campaigns.py）时，您可以使用操作系统的 Shell 将控制台日志输出重定向到文件。

如需将标准输出保存到文件（覆盖任何现有文件），请运行以下命令：

python get_campaigns.py -c $CUSTOMER_ID > campaign_logs.txt

如需将标准输出附加到现有文件，请运行以下命令：

python get_campaigns.py -c $CUSTOMER_ID >> campaign_logs.txt

如需将标准输出和标准错误（针对错误和警告）保存到同一文件，请运行以下命令：

python get_campaigns.py -c $CUSTOMER_ID > all_logs.txt 2>&1

或者，在 Bash 4+ 上：

python get_campaigns.py -c $CUSTOMER_ID &> all_logs.txt

自定义 gRPC 拦截器

Python 客户端库使用 gRPC 拦截器来访问 和记录请求与响应详细信息。您可以通过创建具有自定义逻辑的 gRPC 拦截器来设置自己的自定义日志记录。如需了解详情和 自定义日志记录拦截器的示例，请参阅 日志记录指南。