日志记录

日志记录和监控协同工作,可帮助您了解和优化应用性能,以及诊断错误和系统相关问题。您应该为所有 API 调用开启摘要日志,为失败的 API 调用开启详细日志,以便在需要技术支持时提供 API 通话记录。

客户端库日志记录

Google Ads API 客户端库内置了日志记录功能。如需详细了解针对具体平台的日志记录,请参阅所选客户端库中的日志记录文档。

语言 指南
Java Java 版 Logging 文档
.NET .NET 版 Logging 文档
PHP PHP 版 Logging 文档
Python Python 版 Logging 文档
Ruby Ruby 版 Logging 文档
Perl Perl 日志记录文档

日志格式

Google Ads API 客户端库会为每次 API 调用生成详细日志摘要日志。详细日志包含 API 调用的所有详细信息,而摘要日志包含 API 调用的最少详细信息。下面显示了每种类型的日志的示例,其中日志被截断并设置了格式以提高可读性。

摘要日志

GoogleAds.SummaryRequestLogs Warning: 1 : [2023-09-15 19:58:39Z] -
Request made: Host: , Method: /google.ads.googleads.v14.services.GoogleAdsService/SearchStream,
ClientCustomerID: 5951878031, RequestID: hELhBPNlEDd8mWYcZu7b8g,
IsFault: True, FaultMessage: Status(StatusCode="InvalidArgument",
Detail="Request contains an invalid argument.")

详细日志

GoogleAds.DetailedRequestLogs Verbose: 1 : [2023-11-02 21:09:36Z] -
---------------BEGIN API CALL---------------

Request
-------

Method Name: /google.ads.googleads.v14.services.GoogleAdsService/SearchStream
Host:
Headers: {
  "x-goog-api-client": "gl-dotnet/5.0.0 gapic/17.0.1 gax/4.2.0 grpc/2.46.3 gccl/3.0.1 pb/3.21.5",
  "developer-token": "REDACTED",
  "login-customer-id": "1234567890",
  "x-goog-request-params": "customer_id=4567890123"
}

{ "customerId": "4567890123", "query": "SELECT ad_group_criterion.type FROM
  ad_group_criterion WHERE ad_group.status IN(ENABLED, PAUSED) AND
  campaign.status IN(ENABLED, PAUSED) ", "summaryRowSetting": "NO_SUMMARY_ROW" }

Response
--------
Headers: {
  "date": "Thu, 02 Nov 2023 21:09:35 GMT",
  "alt-svc": "h3-29=\":443\"; ma=2592000"
}

{
  "results": [ {
    "adGroupCriterion": {
      "resourceName": "customers/4567890123/adGroupCriteria/456789456789~123456123467",
      "type": "KEYWORD"
    } }, {
    "adGroupCriterion": {
      "resourceName": "customers/4567890123/adGroupCriteria/456789456789~56789056788",
      "type": "KEYWORD"
    } } ],
    "fieldMask": "adGroupCriterion.type", "requestId": "VsJ4F00ew6s9heHvAJ-abw"
}
----------------END API CALL----------------

如果我不使用客户端库会怎样?

如果您不使用客户端库,请实现自己的日志记录功能,以捕获传出和传入 API 调用的详细信息。您至少应记录 request-id 响应标头的值,然后可根据需要将其分享给技术支持团队

将日志记录到云端

您可以使用许多工具来捕获应用的日志和性能指标。例如,您可以使用 Google Cloud Logging 将性能指标记录到您的 Google Cloud 项目中。这样,您就可以在 Google Cloud Monitoring 中设置信息中心和提醒,以使用记录的指标。

Cloud Logging 为除 Perl 之外的所有受支持的 Google Ads API 客户端库语言提供了客户端库,因此在大多数情况下,您可以直接从客户端库集成使用 Cloud Logging 记录日志。对于其他语言(包括 Perl),Cloud Logging 还提供了 REST API

您可以通过多种方式从 Google Ads API 客户端库记录到 Cloud Logging 或其他工具。每种方法都有自己的实现时间、复杂性和性能权衡。在确定要实现的解决方案之前,请先仔细考虑这些权衡。

方法 1:通过后台进程将本地日志写入云端

您可以通过修改日志记录配置,将客户端库日志写入计算机上的本地文件。将日志输出到本地文件后,您可以设置守护程序来收集日志并将其发送到云端。

此方法的一个局限性是默认情况下无法捕获某些性能指标。客户端库日志包含来自请求和响应对象的详细信息,因此,除非进行其他更改以记录这些指标,否则延迟时间指标不会包含在内。

方法 2:在 Compute Engine 上运行应用并安装 Ops Agent

如果您的应用在 Compute Engine 上运行,您可以通过安装 Ops Agent 来将日志发送到 Google Cloud Logging。除了默认发送的指标和日志之外,您还可以配置将应用日志发送到 Cloud Logging。

如果您的应用已在 Google Cloud 环境中运行,或者如果您正在考虑将应用迁移到 Google Cloud,那么这是一个不错的选择。

方法 3:在应用代码中实现日志记录

可以通过以下两种方式之一直接从应用代码执行日志记录:

  1. 将指标计算和日志语句整合到代码中的每个适用位置。对于规模较小的代码库而言,这种方式更可行,因为此类更改所导致的范围和维护成本微乎其微。

  2. 实现日志记录接口。如果应用逻辑可以进行抽象化处理,以便应用的不同部分从同一基类继承,则可以在该基类中实现日志记录逻辑。通常,这种方式优于在整个应用代码中整合日志语句,因为这种方式更易于维护和扩缩。对于较大的代码库,此解决方案的可维护性和可伸缩性更相关。

这种方法的一个局限性是,应用代码无法获得完整的请求和响应日志。可以通过 gRPC 拦截器访问完整的请求和响应对象;这是内置客户端库日志记录获取请求和响应日志的方式。发生错误时,异常对象中可能提供了其他信息,但应用逻辑中可用于成功响应的详细信息较少。例如,在大多数情况下,无法从 Google Ads API 响应对象访问成功请求的请求 ID。

方法 4:实现自定义 gRPC 日志记录拦截器

gRPC 支持一元和流式拦截器,它们可以在请求和响应对象在客户端和服务器之间传递时访问它们。Google Ads API 客户端库使用 gRPC 拦截器提供内置的日志记录支持。同样,您可以实现自定义 gRPC 拦截器来访问请求和响应对象,提取用于日志记录和监控的信息,并将该数据写入您选择的位置。

与本文介绍的一些其他解决方案不同,实现自定义 gRPC 拦截器可让您灵活地捕获每个请求中的请求和响应对象,并实现额外的逻辑来捕获请求的详细信息。例如,您可以通过在自定义拦截器本身内实现性能计时逻辑来计算请求的所用时间,然后将指标记录到 Google Cloud Logging,使其可用于 Google Cloud Monitoring 中的延迟时间监控。

Python 中的自定义 Google Cloud Logging 拦截器

为了演示此解决方案,我们用 Python 编写了一个自定义日志记录拦截器示例。系统会创建自定义拦截器并将其传递到服务客户端。然后,它会访问在每个服务方法调用中传递的请求和响应对象,处理来自这些对象的数据,并将数据发送到 Google Cloud Logging。

除了来自请求和响应对象的数据之外,该示例还实现一些额外的逻辑来捕获请求的用时,以及一些有助于监控目的(例如请求是否成功)的其他元数据。如需详细了解此信息通常如何用于监控(特别是在结合使用 Google Cloud Logging 和 Google Cloud Monitoring 时),请参阅监控指南

# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""A custom gRPC Interceptor that logs requests and responses to Cloud Logging.

The custom interceptor object is passed into the get_service method of the
GoogleAdsClient. It intercepts requests and responses, parses them into a
human readable structure and logs them using the logging service instantiated
within the class (in this case, a Cloud Logging client).
"""

import logging
import time

from google.cloud import logging
from grpc import UnaryUnaryClientInterceptor, UnaryStreamClientInterceptor

from google.ads.googleads.interceptors import LoggingInterceptor, mask_message


class CloudLoggingInterceptor(LoggingInterceptor):
    """An interceptor that logs rpc request and response details to Google Cloud Logging.

    This class inherits logic from the LoggingInterceptor, which simplifies the
    implementation here. Some logic is required here in order to make the
    underlying logic work -- comments make note of this where applicable.
    NOTE: Inheriting from the LoggingInterceptor class could yield unexpected side
    effects. For example, if the LoggingInterceptor class is updated, this class would
    inherit the updated logic, which could affect its functionality. One option to avoid
    this is to inherit from the Interceptor class instead, and selectively copy whatever
    logic is needed from the LoggingInterceptor class."""

    def __init__(self, api_version):
        """Initializer for the CloudLoggingInterceptor.

        Args:
            api_version: a str of the API version of the request.
        """
        super().__init__(logger=None, api_version=api_version)
        # Instantiate the Cloud Logging client.
        logging_client = logging.Client()
        self.logger = logging_client.logger("cloud_logging")

    def log_successful_request(
        self,
        method,
        customer_id,
        metadata_json,
        request_id,
        request,
        trailing_metadata_json,
        response,
    ):
        """Handles logging of a successful request.

        Args:
            method: The method of the request.
            customer_id: The customer ID associated with the request.
            metadata_json: A JSON str of initial_metadata.
            request_id: A unique ID for the request provided in the response.
            request: An instance of a request proto message.
            trailing_metadata_json: A JSON str of trailing_metadata.
            response: A grpc.Call/grpc.Future instance.
        """
        # Retrieve and mask the RPC result from the response future.
        # This method is available from the LoggingInterceptor class.
        # Ensure self._cache is set in order for this to work.
        # The response result could contain up to 10,000 rows of data,
        # so consider truncating this value before logging it, to save
        # on data storage costs and maintain readability.
        result = self.retrieve_and_mask_result(response)

        # elapsed_ms is the approximate elapsed time of the RPC, in milliseconds.
        # There are different ways to define and measure elapsed time, so use
        # whatever approach makes sense for your monitoring purposes.
        # rpc_start and rpc_end are set in the intercept_unary_* methods below.
        elapsed_ms = (self.rpc_end - self.rpc_start) * 1000

        debug_log = {
            "method": method,
            "host": metadata_json,
            "request_id": request_id,
            "request": str(request),
            "headers": trailing_metadata_json,
            "response": str(result),
            "is_fault": False,
            "elapsed_ms": elapsed_ms,
        }
        self.logger.log_struct(debug_log, severity="DEBUG")

        info_log = {
            "customer_id": customer_id,
            "method": method,
            "request_id": request_id,
            "is_fault": False,
            # Available from the Interceptor class.
            "api_version": self._api_version,
        }
        self.logger.log_struct(info_log, severity="INFO")

    def log_failed_request(
        self,
        method,
        customer_id,
        metadata_json,
        request_id,
        request,
        trailing_metadata_json,
        response,
    ):
        """Handles logging of a failed request.

        Args:
            method: The method of the request.
            customer_id: The customer ID associated with the request.
            metadata_json: A JSON str of initial_metadata.
            request_id: A unique ID for the request provided in the response.
            request: An instance of a request proto message.
            trailing_metadata_json: A JSON str of trailing_metadata.
            response: A JSON str of the response message.
        """
        exception = self._get_error_from_response(response)
        exception_str = self._parse_exception_to_str(exception)
        fault_message = self._get_fault_message(exception)

        info_log = {
            "method": method,
            "endpoint": self.endpoint,
            "host": metadata_json,
            "request_id": request_id,
            "request": str(request),
            "headers": trailing_metadata_json,
            "exception": exception_str,
            "is_fault": True,
        }
        self.logger.log_struct(info_log, severity="INFO")

        error_log = {
            "method": method,
            "endpoint": self.endpoint,
            "request_id": request_id,
            "customer_id": customer_id,
            "is_fault": True,
            "fault_message": fault_message,
        }
        self.logger.log_struct(error_log, severity="ERROR")

    def intercept_unary_unary(self, continuation, client_call_details, request):
        """Intercepts and logs API interactions.

        Overrides abstract method defined in grpc.UnaryUnaryClientInterceptor.

        Args:
            continuation: a function to continue the request process.
            client_call_details: a grpc._interceptor._ClientCallDetails
                instance containing request metadata.
            request: a SearchGoogleAdsRequest or SearchGoogleAdsStreamRequest
                message class instance.

        Returns:
            A grpc.Call/grpc.Future instance representing a service response.
        """
        # Set the rpc_end value to current time when RPC completes.
        def update_rpc_end(response_future):
            self.rpc_end = time.perf_counter()

        # Capture precise clock time to later calculate approximate elapsed
        # time of the RPC.
        self.rpc_start = time.perf_counter()

        # The below call is REQUIRED.
        response = continuation(client_call_details, request)

        response.add_done_callback(update_rpc_end)

        self.log_request(client_call_details, request, response)

        # The below return is REQUIRED.
        return response

    def intercept_unary_stream(
        self, continuation, client_call_details, request
    ):
        """Intercepts and logs API interactions for Unary-Stream requests.

        Overrides abstract method defined in grpc.UnaryStreamClientInterceptor.

        Args:
            continuation: a function to continue the request process.
            client_call_details: a grpc._interceptor._ClientCallDetails
                instance containing request metadata.
            request: a SearchGoogleAdsRequest or SearchGoogleAdsStreamRequest
                message class instance.

        Returns:
            A grpc.Call/grpc.Future instance representing a service response.
        """

        def on_rpc_complete(response_future):
            self.rpc_end = time.perf_counter()
            self.log_request(client_call_details, request, response_future)

        # Capture precise clock time to later calculate approximate elapsed
        # time of the RPC.
        self.rpc_start = time.perf_counter()

        # The below call is REQUIRED.
        response = continuation(client_call_details, request)

        # Set self._cache to the cache on the response wrapper in order to
        # access the streaming logs. This is REQUIRED in order to log streaming
        # requests.
        self._cache = response.get_cache()

        response.add_done_callback(on_rpc_complete)

        # The below return is REQUIRED.
        return response