רישום ביומן ומעקב פועלים יחד כדי לעזור לכם להבין ולבצע אופטימיזציה של ביצועי האפליקציה, וגם כדי לאבחן שגיאות ובעיות שקשורות למערכת. כדאי להפעיל יומני סיכום לכל הקריאות ל-API ויומנים מפורטים לקריאות ל-API שנכשלו, כדי שתוכלו לספק את יומני הקריאות ל-API כשאתם צריכים תמיכה טכנית.
רישום ביומן של ספריית לקוח
ספריות הלקוח של Google Ads API כוללות רישום מובנה ביומן. לפרטים ספציפיים לגבי רישום ביומן בפלטפורמה, אפשר לעיין במסמכי העזרה בנושא רישום ביומן בספריית הלקוח הרצויה.
| שפה | הדרכות |
|---|---|
| Java | רישום ביומן של מסמכי Java |
| .NET | מאמרי עזרה בנושא רישום ביומן עבור .NET |
| PHP | מסמכי רישום ביומן ל-PHP |
| Python | Logging docs for Python |
| Ruby | Logging docs for Ruby |
| Perl | Logging docs for 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.
יש כמה אפשרויות לרישום ביומן ב-Cloud Logging או בכלי אחר, מתוך ספריית לקוח של Google Ads API. לכל אפשרות יש יתרונות וחסרונות משלה מבחינת הזמן שנדרש להטמעה, המורכבות והביצועים. כדאי לשקול היטב את הפשרות האלה לפני שמחליטים איזו פתרון להטמיע.
אפשרות 1: כתיבת יומני אירועים מקומיים לענן מתהליך ברקע
אפשר לכתוב את היומנים של ספריית הלקוח לקובץ מקומי במחשב על ידי שינוי הגדרות הרישום ביומן. אחרי שהיומנים מועברים לקובץ מקומי, אפשר להגדיר דמון לאיסוף היומנים ולשליחתם לענן.
אחד החסרונות בגישה הזו הוא שחלק ממדדי הביצועים לא נרשמים כברירת מחדל. יומנים של ספריות לקוח כוללים פרטים מאובייקטים של בקשות ותגובות, ולכן מדדי זמן האחזור לא ייכללו אלא אם יבוצעו שינויים נוספים כדי לרשום גם אותם ביומן.
אפשרות 2: מריצים את האפליקציה ב-Compute Engine ומתקינים את סוכן התפעול
אם האפליקציה שלכם פועלת ב-Compute Engine, אתם יכולים לשלוח את היומנים ל-Google Cloud Logging על ידי התקנת סוכן התפעול. אפשר להגדיר את Ops Agent כך שישלח את יומני האפליקציות שלכם ל-Cloud Logging, בנוסף למדדים וליומנים שנשלחים כברירת מחדל.
אם האפליקציה כבר פועלת בסביבת Google Cloud, או אם אתם שוקלים להעביר את האפליקציה ל-Google Cloud, זו אפשרות מצוינת שכדאי לשקול.
אפשרות 3: הטמעת רישום ביומן בקוד האפליקציה
אפשר להתחבר ישירות מקוד האפליקציה באחת משתי דרכים:
שילוב חישובי מדדים והצהרות יומן בכל מיקום רלוונטי בקוד. האפשרות הזו מתאימה יותר לבסיסי קוד קטנים יותר, שבהם ההיקף ועלויות התחזוקה של שינוי כזה יהיו מינימליים.
הטמעה של ממשק רישום ביומן. אם אפשר לבצע הפשטה של הלוגיקה של האפליקציה כך שחלקים שונים של האפליקציה יירשו מאותה מחלקת בסיס, אפשר להטמיע את לוגיקת הרישום באותה מחלקת בסיס. בדרך כלל עדיף להשתמש באפשרות הזו במקום לשלב הצהרות יומן בקוד האפליקציה, כי קל יותר לתחזק אותה ולהרחיב אותה. בבסיסי קוד גדולים יותר, התחזוקה וההתאמה של הפתרון הזה חשובות במיוחד.
מגבלה אחת של הגישה הזו היא שיומני הבקשות והתגובות המלאים לא זמינים מקוד האפליקציה. אפשר לגשת לאובייקטים מלאים של בקשות ותגובות באמצעות interceptors של gRPC. כך מתקבלים יומני בקשות ותגובות ביומן של ספריית הלקוח המובנית. במקרה של שגיאה, יכול להיות שיהיה מידע נוסף באובייקט החריגה, אבל בתגובות מוצלחות יש פחות פרטים בלוגיקה של האפליקציה. לדוגמה, ברוב המקרים, אי אפשר לגשת למזהה הבקשה של בקשה שהסתיימה בהצלחה מאובייקטי התגובה של Google Ads API.
אפשרות 4: הטמעה של interceptor מותאם אישית לרישום ביומן ב-gRPC
gRPC תומך במיירטים (interceptors) של בקשות יחידות ושל סטרימינג, שיכולים לגשת לאובייקטים של הבקשה והתגובה כשהם עוברים בין הלקוח לשרת. ספריות הלקוח של Google Ads API משתמשות ב-interceptors של gRPC כדי להציע תמיכה מובנית ברישום ביומן. באופן דומה, אפשר להטמיע gRPC interceptor מותאם אישית כדי לגשת לאובייקטים של הבקשה והתגובה, לחלץ מידע למטרות רישום ביומן ומעקב, ולכתוב את הנתונים האלה למיקום שתבחרו.
בשונה מפתרונות אחרים שמוצגים כאן, הטמעה של interceptor מותאם אישית של gRPC מאפשרת לכם ללכוד אובייקטים של בקשות ותשובות בכל בקשה, ולהטמיע לוגיקה נוספת ללכידת פרטים של הבקשה. לדוגמה, אפשר לחשב את הזמן שחלף מאז שליחת הבקשה על ידי הטמעה של לוגיקה של תזמון ביצועים בתוך ה-interceptor המותאם אישית עצמו, ואז לרשום את המדד ב-Google Cloud Logging כדי שהוא יהיה זמין למעקב אחרי זמן האחזור ב-Google Cloud Monitoring.
Custom Google Cloud Logging interceptor in Python
כדי להמחיש את הפתרון הזה, כתבנו דוגמה של קוד Python לרישום מותאם אישית של פעולות. ה-interceptor בהתאמה אישית נוצר ומועבר ללקוח השירות. לאחר מכן, הוא ניגש לאובייקטים של הבקשה והתגובה שעוברים בכל קריאה לשיטת שירות, מעבד את הנתונים מהאובייקטים האלה ושולח את הנתונים ל-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 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