日志记录和监控功能会协同工作，以帮助您了解和优化应用性能，并诊断错误和系统相关问题。您应为所有 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 为所有受支持的 Google Ads API 客户端库语言（Perl 除外）提供了客户端库，因此在大多数情况下，可以直接从客户端库集成中使用 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。除了默认发送的指标和日志之外，您还可以将 Ops Agent 配置为向 Cloud Logging 发送应用日志。
如果您的应用已在 Google Cloud 环境中运行，或者如果您正在考虑将应用迁移到 Google Cloud，那么这是一个不错的选择。
方法 3：在应用代码中实现日志记录
可通过以下两种方式之一，直接从应用代码记录日志：
将指标计算和日志语句整合到代码中的每个适用位置。对于规模较小的代码库而言，此方案更可行，因为此类更改的范围和维护成本微乎其微。
实现日志记录接口。如果应用逻辑可以抽象化，以便应用的不同部分从同一个基类继承，则可以在该基类中实现日志记录逻辑。通常，此方法优于在整个应用代码中纳入日志语句，因为它更易于维护和扩缩。对于较大的代码库，此解决方案的可维护性和可伸缩性更为相关。
这种方法的一个限制是，应用代码中不提供完整的请求和响应日志。可以从 gRPC 拦截器访问完整的请求和响应对象；这就是内置客户端库日志记录获取请求和响应日志的方式。如果发生错误，异常对象中可能会提供更多相关信息，但应用逻辑中可用于成功响应的详细信息较少。例如，在大多数情况下，成功请求的请求 ID 无法从 Google Ads API 响应对象中访问。
选项 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 时），请参阅 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