El registro y la supervisión funcionan en conjunto para ayudarte a comprender y optimizar el rendimiento de las aplicaciones, así como a 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 para las llamadas fallidas a la API, de modo que puedas proporcionar los registros de llamadas a la API cuando necesites asistencia técnica.
Registro de la biblioteca cliente
Las bibliotecas cliente de la API de Google Ads incluyen un registro integrado. Para obtener detalles de registro específicos de la plataforma, consulta la documentación de registro en 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 |
| Ruby | 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 los detalles mínimos de la llamada a la API. Se muestra un ejemplo de cada tipo de registro, con los registros truncados y formateados 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
Existen 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 utilizar las métricas registradas.
Cloud Logging ofrece bibliotecas cliente para todos los lenguajes de la biblioteca cliente de la API de Google Ads compatibles, 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.
Existen algunas opciones para registrarte en Cloud Logging o en otra herramienta desde una biblioteca cliente de la API de Google Ads. Cada opción tiene sus propias ventajas y desventajas en cuanto al tiempo de implementación, la complejidad y el rendimiento. Piensa con cuidado en estas ventajas y desventajas antes de decidir qué solución implementar.
Opción 1: Escribe registros locales en la nube desde un proceso en segundo plano
Puedes modificar la configuración de registro para escribir los registros de la biblioteca cliente en un archivo local de tu máquina. Una vez que los registros se envían a un archivo local, puedes configurar un daemon para recopilarlos y enviarlos 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 las métricas de latencia no se incluirán a menos que se realicen cambios adicionales para registrarlas también.
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 tus registros a Google Cloud Logging instalando 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 trasladarla a Google Cloud, esta es una excelente opción para tener en cuenta.
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 declaraciones de registro en cada ubicación aplicable de tu código Esta opción es más factible para bases de código más pequeñas, en las que el alcance y los costos de mantenimiento de un cambio de este tipo serían mínimos.
Implementa una interfaz de registro. Si la lógica de la aplicación se puede abstraer de modo que diferentes partes de la aplicación hereden de la misma clase base, la lógica de registro se puede implementar en esa clase base. En general, esta opción es preferible a la incorporación de instrucciones de registro en todo el código de la aplicación, ya que es más fácil de mantener y escalar. Para las 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 solicitudes y respuestas no están disponibles desde el código de la aplicación. Se puede acceder a los objetos de solicitud y respuesta completos desde los interceptores de gRPC. Así es como el registro de la biblioteca cliente integrada obtiene los registros de solicitud y respuesta. En caso de error, es posible que haya información adicional disponible en el objeto de excepción, pero hay menos detalles disponibles para las respuestas exitosas 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 exitosa 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 el registro. Del mismo modo, puedes implementar un interceptor de gRPC personalizado para acceder a los objetos de solicitud y respuesta, extraer información para fines de registro y supervisión, y escribir esos datos en la ubicación que elijas.
A diferencia de otras soluciones que se presentan aquí, implementar un interceptor de gRPC personalizado te brinda flexibilidad para capturar objetos de solicitud y respuesta en cada solicitud, y para implementar lógica adicional para capturar detalles de la solicitud. Por ejemplo, puedes calcular el tiempo transcurrido de una solicitud implementando la lógica de sincronización del rendimiento dentro del interceptor personalizado y, luego, registrar la métrica en Google Cloud Logging para que esté disponible para la supervisión de la 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. Se crea el interceptor personalizado y se pasa al cliente del servicio. Luego, accede a los objetos de solicitud y respuesta que pasan por cada llamada al método de servicio, procesa los datos de esos objetos y envía los datos a Google Cloud Logging.
Además de los datos que provienen de los objetos de solicitud y respuesta, el ejemplo implementa cierta lógica adicional para capturar el tiempo transcurrido de la solicitud y otros metadatos que serían útiles para 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 de forma general para la supervisión como específicamente cuando se combinan Google Cloud Logging y Google Cloud Monitoring, consulta la Guía de supervisión.
# 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 time from typing import Any, Callable, Dict, Optional from google.cloud import logging as google_cloud_logging from grpc._interceptor import _ClientCallDetails from google.ads.googleads.interceptors import LoggingInterceptor 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: str): """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: google_cloud_logging.Client = google_cloud_logging.Client() self.logger: google_cloud_logging.Logger = logging_client.logger("cloud_logging") self.rpc_start: float self.rpc_end: float def log_successful_request( self, method: str, customer_id: Optional[str], metadata_json: str, request_id: str, request: Any, # google.ads.googleads.vX.services.types.SearchGoogleAdsRequest or SearchGoogleAdsStreamRequest trailing_metadata_json: str, response: Any, # grpc.Call or grpc.Future ) -> None: """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: Any = 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: float = (self.rpc_end - self.rpc_start) * 1000 debug_log: Dict[str, Any] = { "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: Dict[str, Any] = { "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: str, customer_id: Optional[str], metadata_json: str, request_id: str, request: Any, # google.ads.googleads.vX.services.types.SearchGoogleAdsRequest or SearchGoogleAdsStreamRequest trailing_metadata_json: str, response: Any, # grpc.Call or grpc.Future ) -> None: """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: Any = self._get_error_from_response(response) exception_str: str = self._parse_exception_to_str(exception) fault_message: str = self._get_fault_message(exception) info_log: Dict[str, Any] = { "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: Dict[str, Any] = { "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: Callable[[_ClientCallDetails, Any], Any], # Any is request type client_call_details: _ClientCallDetails, request: Any, # google.ads.googleads.vX.services.types.SearchGoogleAdsRequest ) -> Any: # grpc.Call or grpc.Future """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: Any) -> None: # response_future is grpc.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: Any = continuation(client_call_details, request) # response is grpc.Call or grpc.Future 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: Callable[[_ClientCallDetails, Any], Any], # Any is request type client_call_details: _ClientCallDetails, request: Any, # google.ads.googleads.vX.services.types.SearchGoogleAdsStreamRequest ) -> Any: # grpc.Call or grpc.Future """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: Any) -> None: # response_future is grpc.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: Any = continuation(client_call_details, request) # response is grpc.Call or grpc.Future # 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