El registro y la supervisión funcionan en conjunto para ayudarte a comprender y optimizar el rendimiento de las aplicaciones, además de diagnosticar errores y problemas relacionados con el sistema. Debes activar los registros de resumen para todas las llamadas a la API y los registros detallados de las llamadas a la API fallidas, de modo que puedas proporcionar los registros de llamadas a la API cuando necesites asistencia técnica.
Registro de bibliotecas cliente
Las bibliotecas cliente de la API de Google Ads incluyen registros integrados. Para obtener detalles de registro específicos de la plataforma, consulta la documentación de registro dentro de la biblioteca cliente que elijas.
| Idioma | Guía |
|---|---|
| Java | Documentos de Logging para Java |
| .NET | Documentos de Logging para .NET |
| PHP | Documentos de Logging para PHP |
| Python | Documentos de Logging para Python |
| Rita | Documentos de Logging para Ruby |
| Perl | Documentos de Logging para Perl |
Formato de registro
Las bibliotecas cliente de la API de Google Ads generan un registro detallado y un registro de resumen para cada llamada a la API. El registro detallado contiene todos los detalles de la llamada a la API, mientras que el registro de resumen contiene detalles mínimos de la llamada a la API. Se muestra un ejemplo de cada tipo de registro, con los registros truncados y con un formato para facilitar la lectura.
Registro de resumen
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.")
Registro detallado
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----------------
¿Qué sucede si no uso una biblioteca cliente?
Si no usas una biblioteca cliente, implementa tu propio registro para capturar los detalles de las llamadas a la API entrantes y salientes. Debes registrar al menos el
valor del encabezado de respuesta request-id, que luego se puede compartir con los
equipos de asistencia técnica según sea necesario.
Registro en la nube
Hay muchas herramientas que puedes usar para capturar registros y métricas de rendimiento de tu aplicación. Por ejemplo, puedes usar Google Cloud Logging para registrar métricas de rendimiento en tu proyecto de Google Cloud. Esto permite configurar paneles y alertas en Google Cloud Monitoring para usar las métricas registradas.
Cloud Logging ofrece bibliotecas cliente para todos los lenguajes de biblioteca cliente de la API de Google Ads, excepto Perl, por lo que en la mayoría de los casos es posible registrar con Cloud Logging directamente desde la integración de tu biblioteca cliente. Para otros lenguajes, incluido Perl, Cloud Logging también ofrece una API de REST.
Hay varias opciones para acceder a Cloud Logging o a otra herramienta desde una biblioteca cliente de la API de Google Ads. Cada opción incluye sus propias compensaciones de tiempo para la implementación, complejidad y rendimiento. Piensa detenidamente en estas compensaciones antes de decidir qué solución implementar.
Opción 1: Escribe registros locales en la nube desde un proceso en segundo plano
Los registros de la biblioteca cliente se pueden escribir en un archivo local en tu máquina si modificas la configuración de registro. Una vez que los registros se envían a un archivo local, puedes configurar un daemon para que recopile los registros y los envíe a la nube.
Una limitación de este enfoque es que algunas métricas de rendimiento no se capturarán de forma predeterminada. Los registros de la biblioteca cliente incluyen detalles de los objetos de solicitud y respuesta, por lo que no se incluirán las métricas de latencia, a menos que se realicen cambios adicionales para registrarlas.
Opción 2: Ejecuta tu aplicación en Compute Engine y, luego, instala el Agente de operaciones
Si tu aplicación se ejecuta en Compute Engine, puedes enviar los registros a Google Cloud Logging si instalas el Agente de operaciones. El Agente de operaciones se puede configurar para enviar los registros de tu aplicación a Cloud Logging, además de las métricas y los registros que se envían de forma predeterminada.
Si tu aplicación ya se ejecuta en un entorno de Google Cloud o si estás considerando trasladar tu aplicación a Google Cloud, esta es una gran opción para considerar.
Opción 3: Implementa el registro en el código de tu aplicación
El registro directamente desde el código de la aplicación se puede realizar de dos maneras:
Incorporar cálculos de métricas y instrucciones de registro en cada ubicación aplicable en tu código Esta opción es más viable para bases de código más pequeñas, en las que los costos de alcance y mantenimiento de ese cambio serían mínimos.
Implementar una interfaz de registro Si la lógica de la aplicación se puede abstraer para que diferentes partes de la aplicación se hereden de la misma clase base, la lógica de registro se puede implementar en esa clase base. Por lo general, se prefiere esta opción en lugar de incorporar instrucciones de registro en todo el código de la aplicación, ya que es más fácil de mantener y escalar. Para bases de código más grandes, la capacidad de mantenimiento y la escalabilidad de esta solución son aún más relevantes.
Una limitación de este enfoque es que los registros completos de solicitud y respuesta no están disponibles en el código de la aplicación. Se puede acceder a los objetos completos de solicitud y respuesta desde los interceptores de gRPC; así es como el registro integrado de la biblioteca cliente obtiene los registros de solicitud y respuesta. En caso de que se produzca un error, es posible que haya información adicional disponible en el objeto de excepción, pero hay menos detalles disponibles sobre las respuestas correctas dentro de la lógica de la aplicación. Por ejemplo, en la mayoría de los casos, no se puede acceder al ID de solicitud de una solicitud correcta desde los objetos de respuesta de la API de Google Ads.
Opción 4: Implementa un interceptor de registro de gRPC personalizado
gRPC admite interceptores unarios y de transmisión que pueden acceder a los objetos de solicitud y respuesta a medida que pasan entre el cliente y el servidor. Las bibliotecas cliente de la API de Google Ads usan interceptores de gRPC para ofrecer compatibilidad integrada con registros. De manera similar, puedes implementar un interceptor de gRPC personalizado para acceder a los objetos de solicitud y respuesta, extraer información con fines de registro y supervisión, y escribir esos datos en la ubicación que elijas.
A diferencia de algunas de las otras soluciones que se presentan aquí, la implementación de un interceptor de gRPC personalizado te brinda flexibilidad para capturar objetos de solicitud y respuesta en cada solicitud, además de implementar lógica adicional para capturar los detalles de la solicitud. Por ejemplo, puedes calcular el tiempo transcurrido de una solicitud si implementas la lógica de sincronización del rendimiento dentro del interceptor personalizado y, luego, registras la métrica en Google Cloud Logging a fin de que esté disponible para la supervisión de latencia en Google Cloud Monitoring.
Interceptor personalizado de Google Cloud Logging en Python
Para demostrar esta solución, escribimos un ejemplo de un interceptor de registro personalizado en Python. El interceptor personalizado se crea y se pasa al cliente de servicio. Luego, accede a los objetos de solicitud y respuesta que pasan en cada llamada de método de servicio, procesa los datos de esos objetos y los envía a Google Cloud Logging.
Además de los datos que provienen de los objetos de solicitud y respuesta, en el ejemplo, se implementa una lógica adicional para capturar el tiempo transcurrido de la solicitud y algunos otros metadatos que serían útiles con fines de supervisión, como si la solicitud se realizó correctamente o no. Para obtener más información sobre cómo esta información puede ser útil, tanto en general para la supervisión como cuando se combinan Google Cloud Logging y Google Cloud Monitoring, consulta la Guía de 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