רישום ביומן ומעקב פועלים יחד כדי לעזור לכם להבין ולבצע אופטימיזציה של ביצועי האפליקציה, וגם כדי לאבחן שגיאות ובעיות שקשורות למערכת. מומלץ להפעיל יומני סיכום לכל הקריאות ל-API ויומנים מפורטים לקריאות ל-API שנכשלו, כדי שתוכלו לספק את יומני הקריאות ל-API כשתרצו לקבל תמיכה טכנית.
רישום ביומן של ספריית לקוח
ספריות הלקוח של Google Ads API כוללות רישום ביומן מובנה. לפרטים ספציפיים לפלטפורמה בנושא רישום ביומן, אפשר לעיין במסמכי העזרה בנושא רישום ביומן בספריית הלקוח שבחרתם.
פורמט היומן
ספריות הלקוח של 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 מציע גם API ל-REST.
יש כמה אפשרויות לתיעוד ביומן ב-Cloud Logging או בכלי אחר מתוך ספריית לקוח של Google Ads API. לכל אפשרות יש יתרונות וחסרונות משלה מבחינת זמן ההטמעה, המורכבות והביצועים. כדאי לחשוב היטב על הפשרות האלה לפני שמחליטים איזה פתרון להטמיע.
אפשרות 1: כתיבת יומנים מקומיים בענן מתהליך רקע
אפשר לשנות את הגדרות הרישום ביומן כדי לכתוב יומנים של ספריית לקוח לקובץ מקומי במחשב. אחרי שהיומן יופיע בקובץ מקומי, תוכלו להגדיר דימון (daemon) שיאסוף את היומנים וישלח אותם לענן.
אחת מהמגבלות של הגישה הזו היא שחלק ממדדי הביצועים לא יתועדו כברירת מחדל. יומני ספריית הלקוח כוללים פרטים מהבקשה ומאובייקט התגובה, כך שמדדי זמן האחזור לא ייכללו אלא אם יבוצעו שינויים נוספים כדי לתעד אותם גם כן.
אפשרות 2: מפעילים את האפליקציה ב-Compute Engine ומתקינים את סוכן התפעול
אם האפליקציה שלכם פועלת ב-Compute Engine, תוכלו להתקין את Ops Agent כדי לשלוח את היומנים ל-Google Cloud Logging. אפשר להגדיר את Ops Agent כך שישלח את יומני האפליקציות ל-Cloud Logging, בנוסף למדדים והיומנים שנשלחים כברירת מחדל.
אם האפליקציה שלכם כבר פועלת בסביבת Google Cloud, או אם אתם שוקלים להעביר את האפליקציה ל-Google Cloud, זו אפשרות נהדרת.
אפשרות 3: הטמעת רישום ביומן בקוד האפליקציה
אפשר לתעד ביומן ישירות מקוד האפליקציה באחת משתי דרכים:
שילוב של חישובי מדדים ודפי יומן בכל מיקום רלוונטי בקוד. האפשרות הזו מתאימה יותר לבסיסי קוד קטנים יותר, שבהם היקף השינוי ועלויות התחזוקה שלו יהיו מינימליים.
הטמעת ממשק לתיעוד ביומן. אם אפשר ליצור הפשטה של לוגיקת האפליקציה כך שחלקים שונים באפליקציה יורשים מאותה כיתה בסיס, אפשר להטמיע את לוגיקת הרישום ביומן בכיתה הבסיסית הזו. בדרך כלל, האפשרות הזו עדיפה על פני שילוב של הצהרות יומן בקוד האפליקציה, כי קל יותר לתחזק אותה ולשנות את ההיקף שלה. ככל שבסיס הקוד גדול יותר, כך היכולת לשמור על הפתרון הזה ולשנות אותו בהתאם לצרכים הולכת ונעשית רלוונטית יותר.
אחת המגבלות של הגישה הזו היא שלוגים המלאים של הבקשות והתשובות לא זמינים מקוד האפליקציה. אפשר לגשת לאובייקטים מלאים של בקשות ותשובות ממתווכני gRPC. כך מתקבלים יומני הבקשות והתשובות ביומן המובנה של ספריית הלקוח. במקרה של שגיאה, יכול להיות שיהיה מידע נוסף באובייקט החריג, אבל יש פחות פרטים בתגובות מוצלחות בתוך הלוגיקה של האפליקציה. לדוגמה, ברוב המקרים אי אפשר לגשת למזהה הבקשה של בקשה שהסתיימה בהצלחה מאובייקטי התגובה של Google Ads API.
אפשרות 4: הטמעת מתווך מותאם אישית לתיעוד ביומן של gRPC
gRPC תומך במחסומים חד-פעמיים ובמחסומים בסטרימינג, שיכולים לגשת לאובייקטים של הבקשה והתגובה בזמן שהם עוברים בין הלקוח לשרת. בספריות הלקוח של Google Ads API נעשה שימוש במעכבי gRPC כדי לספק תמיכה מובנית ברישום ביומן. באופן דומה, אפשר להטמיע מתווך gRPC מותאם אישית כדי לגשת לאובייקטים של הבקשה והתגובה, לחלץ מידע לצורכי רישום ביומן ומעקב ולכתוב את הנתונים האלה במיקום שבחרתם.
בניגוד לחלק מהפתרונות האחרים שמפורטים כאן, הטמעת Interceptor בהתאמה אישית של gRPC מאפשרת לכם לתעד אובייקטים של בקשות ותשובות בכל בקשה, ולהטמיע לוגיקה נוספת כדי לתעד את פרטי הבקשה. לדוגמה, אפשר לחשב את משך הזמן שחלף מאז שליחת הבקשה על ידי הטמעת לוגיקה של תזמון ביצועים בתוך המנטר המותאם אישית עצמו, ואז לתעד את המדד ביומן Google Cloud Logging כדי שיהיה זמין למעקב אחר זמן האחזור ב-Google Cloud Monitoring.
מתווך מותאם אישית של Google Cloud Logging ב-Python
כדי להמחיש את הפתרון הזה, כתבנו דוגמה למעכב מותאם אישית של רישום ביומן ב-Python. מפעיל ההתערבות בהתאמה אישית נוצר ומועבר ללקוח השירות. לאחר מכן הוא ניגש לאובייקטים של הבקשה והתגובה שעוברים בכל קריאה ל-method של השירות, מעבד את הנתונים מהאובייקטים האלה ושולח את הנתונים ל-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