Logging und Monitoring arbeiten zusammen, damit Sie die Anwendungsleistung besser verstehen und optimieren sowie Fehler und Systemprobleme diagnostizieren können. Sie sollten Zusammenfassungslogs für alle API-Aufrufe und detaillierte Logs für fehlgeschlagene API-Aufrufe aktivieren, damit Sie die API-Aufrufprotokolle bereitstellen können, wenn Sie technischen Support benötigen.
Logging der Clientbibliothek
Die Google Ads API-Clientbibliotheken verfügen über eine integrierte Protokollierung. Informationen zu den plattformspezifischen Logging-Funktionen finden Sie in der Logging-Dokumentation in der Clientbibliothek Ihrer Wahl.
| Sprache | Leitfaden |
|---|---|
| Java | Logging-Dokumentation für Java |
| .NET | Logging-Dokumente für .NET |
| PHP | Logging-Dokumente für PHP |
| Python | Logging-Dokumentation für Python |
| Ruby | Logging-Dokumente für Ruby |
| Perl | Logging-Dokumente für Perl |
Logformat
Die Google Ads API-Clientbibliotheken generieren für jeden API-Aufruf ein detailliertes Protokoll und eine Zusammenfassung. Das detaillierte Log enthält alle Details des API-Aufrufs, während das Zusammenfassungslog nur minimale Details des API-Aufrufs enthält. Für jeden Logtyp wird ein Beispiel gezeigt, wobei die Logs gekürzt und zur besseren Lesbarkeit formatiert sind.
Zusammenfassungsprotokoll
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.")
Detailliertes Protokoll
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----------------
Was ist, wenn ich keine Clientbibliothek verwende?
Wenn Sie keine Clientbibliothek verwenden, implementieren Sie ein eigenes Logging, um die Details der ausgehenden und eingehenden API-Aufrufe zu erfassen. Sie sollten mindestens den Wert des Antwortheaders request-id protokollieren. Dieser kann dann bei Bedarf an die Teams des technischen Supportteams weitergegeben werden.
In der Cloud protokollieren
Es gibt viele Tools, mit denen Sie Logs und Leistungsmesswerte für Ihre Anwendung erfassen können. Sie können beispielsweise Google Cloud Logging verwenden, um Leistungsmesswerte in Ihrem Google Cloud-Projekt zu protokollieren. Dadurch haben Sie die Möglichkeit, Dashboards und Benachrichtigungen in Google Cloud Monitoring einzurichten, um die protokollierten Messwerte zu nutzen.
Cloud Logging bietet Clientbibliotheken für alle unterstützten Sprachen der Google Ads API-Clientbibliotheken mit Ausnahme von Perl. Daher ist es in den meisten Fällen möglich, Logs direkt über die Integration der Clientbibliothek zu erstellen. Für andere Sprachen, einschließlich Perl, bietet Cloud Logging auch eine REST API.
Es gibt verschiedene Möglichkeiten, sich über die Google Ads API-Clientbibliothek in Cloud Logging oder ein anderes Tool zu protokollieren. Jede Option hat ihre eigenen Vor- und Nachteile bei der Implementierung, Komplexität und Leistung. Bedenken Sie diese Vor- und Nachteile, bevor Sie sich für eine Lösung entscheiden.
Option 1: Lokale Logs aus einem Hintergrundprozess in die Cloud schreiben
Logs von Clientbibliotheken können durch Ändern der Logging-Konfiguration in eine lokale Datei auf Ihrem Computer geschrieben werden. Sobald die Logs in einer lokalen Datei ausgegeben werden, können Sie einen Daemon einrichten, der die Logs erfasst und an die Cloud sendet.
Eine Einschränkung dieses Ansatzes besteht darin, dass einige Leistungsmesswerte nicht standardmäßig erfasst werden. Clientbibliotheken enthalten Details aus den Anfrage- und Antwortobjekten, sodass Latenzmesswerte nur enthalten sind, wenn zusätzliche Änderungen vorgenommen werden, um diese ebenfalls zu protokollieren.
Option 2: Anwendung auf Compute Engine ausführen und Ops-Agent installieren
Wenn Ihre Anwendung in Compute Engine ausgeführt wird, können Sie den Ops-Agent installieren, um Ihre Logs an Google Cloud Logging zu senden. Der Ops-Agent kann so konfiguriert werden, dass er Ihre Anwendungslogs zusätzlich zu den standardmäßigen Messwerten und Logs an Cloud Logging sendet.
Wenn Ihre Anwendung bereits in einer Google Cloud-Umgebung ausgeführt wird oder Sie überlegen, sie zu Google Cloud zu verschieben, ist dies eine gute Option.
Option 3: Logging im Anwendungscode implementieren
Ein Logging direkt aus dem Anwendungscode kann auf zwei Arten erfolgen:
Einbindung von Messwertberechnungen und Loganweisungen an jeder entsprechenden Stelle im Code Diese Option ist für kleinere Codebasen besser geeignet, bei denen der Umfang und die Wartungskosten einer solchen Änderung minimal wären.
Logging-Schnittstelle implementieren Wenn die Anwendungslogik abstrahiert werden kann, sodass verschiedene Teile der Anwendung von derselben Basisklasse übernehmen, kann die Logging-Logik in dieser Basisklasse implementiert werden. Diese Option ist im Allgemeinen gegenüber dem Einbinden von Loganweisungen im gesamten Anwendungscode zu bevorzugen, da sie einfacher zu verwalten und zu skalieren ist. Bei größeren Codebasen sind die Verwaltbarkeit und Skalierbarkeit dieser Lösung umso relevanter.
Eine Einschränkung dieses Ansatzes besteht darin, dass die vollständigen Anfrage- und Antwortlogs nicht im Anwendungscode verfügbar sind. Auf vollständige Anfrage- und Antwortobjekte kann von gRPC-Interceptoren zugegriffen werden. Auf diese Weise erhält das integrierte Logging der Clientbibliothek Anfrage- und Antwortlogs. Im Falle eines Fehlers sind im Ausnahmeobjekt möglicherweise zusätzliche Informationen verfügbar. Für erfolgreiche Antworten in der Anwendungslogik sind jedoch weniger Details verfügbar. Beispielsweise ist die Anfrage-ID bei einer erfolgreichen Anfrage in den meisten Fällen nicht über die Google Ads API-Antwortobjekte zugänglich.
Option 4: Benutzerdefinierten gRPC-Logging-Interceptor implementieren
gRPC unterstützt unäre und Streaming-Abfangpunkte, die auf die Anfrage- und Antwortobjekte zugreifen können, während sie zwischen dem Client und dem Server übertragen werden. Die Google Ads API-Clientbibliotheken verwenden gRPC-Interceptoren, um integrierte Logging-Unterstützung zu bieten. Ebenso können Sie einen benutzerdefinierten gRPC-Interceptor implementieren, um auf die Anfrage- und Antwortobjekte zuzugreifen, Informationen für Logging- und Monitoringzwecke zu extrahieren und diese Daten an den Speicherort Ihrer Wahl zu schreiben.
Im Gegensatz zu anderen hier vorgestellten Lösungen bietet Ihnen die Implementierung eines benutzerdefinierten gRPC-Interceptor die Flexibilität, Anfrage- und Antwortobjekte bei jeder Anfrage zu erfassen und zusätzliche Logik zum Erfassen von Details der Anfrage zu implementieren. Sie können beispielsweise die verstrichene Zeit einer Anfrage berechnen, indem Sie im benutzerdefinierten Interceptor selbst eine Logik für die Leistungsoptimierung implementieren. Anschließend können Sie den Messwert in Google Cloud Logging protokollieren, damit er für das Latenzmonitoring in Google Cloud Monitoring verfügbar ist.
Benutzerdefinierter Google Cloud Logging-Interceptor in Python
Zur Demonstration dieser Lösung haben wir ein Beispiel für einen benutzerdefinierten Logging-Interceptor in Python geschrieben. Der benutzerdefinierte Interceptor wird erstellt und an den Dienstclient übergeben. Anschließend greift er auf die Anfrage- und Antwortobjekte zu, die bei jedem Aufruf der Dienstmethode übergeben werden, verarbeitet Daten aus diesen Objekten und sendet die Daten an Google Cloud Logging.
Zusätzlich zu den Daten, die von den Anfrage- und Antwortobjekten stammen, implementiert das Beispiel eine zusätzliche Logik, um die verstrichene Zeit der Anfrage und einige andere Metadaten zu erfassen, die für Monitoringzwecke nützlich sind, z. B. ob die Anfrage erfolgreich war oder nicht. Weitere Informationen dazu, wie diese Informationen im Allgemeinen für das Monitoring und insbesondere bei der Kombination von Google Cloud Logging und Google Cloud Monitoring nützlich sein können, finden Sie im Leitfaden zu 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