ثبت وقایع و نظارت به طور همزمان کار می‌کنند تا به شما در درک و بهینه‌سازی عملکرد برنامه و همچنین تشخیص خطاها و مشکلات مربوط به سیستم کمک کنند. شما باید گزارش‌های خلاصه را برای همه فراخوانی‌های API و گزارش‌های دقیق را برای فراخوانی‌های ناموفق API فعال کنید تا بتوانید در صورت نیاز به پشتیبانی فنی، گزارش‌های تماس API را ارائه دهید.
ثبت وقایع کتابخانه کلاینت
کتابخانه‌های کلاینت API گوگل ادز دارای قابلیت ثبت وقایع (logging) داخلی هستند. برای جزئیات ثبت وقایع مختص پلتفرم، به مستندات ثبت وقایع در کتابخانه کلاینت مورد نظر خود مراجعه کنید.
| زبان | راهنما |
|---|---|
| جاوا | ثبت اسناد برای جاوا |
| دات نت | ثبت اسناد برای .NET |
| پی اچ پی | ثبت اسناد برای PHP |
| پایتون | ثبت اسناد برای پایتون |
| روبی | ثبت اسناد برای روبی |
| پرل | ثبت اسناد برای Perl |
قالب گزارش
کتابخانه‌های کلاینت 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 کتابخانه‌های کلاینت را برای همه زبان‌های پشتیبانی‌شده برای کتابخانه کلاینت API گوگل ادز به جز Perl ارائه می‌دهد، بنابراین در بیشتر موارد می‌توان مستقیماً از طریق یکپارچه‌سازی کتابخانه کلاینت خود با Cloud Logging لاگ گرفت. برای زبان‌های دیگر از جمله Perl، Cloud Logging یک REST API نیز ارائه می‌دهد.
چندین گزینه برای ورود به Cloud Logging یا ابزار دیگری از کتابخانه کلاینت API گوگل ادز وجود دارد. هر گزینه با معایب و مزایای خاص خود از نظر زمان پیاده‌سازی، پیچیدگی و عملکرد همراه است. قبل از تصمیم‌گیری در مورد اینکه کدام راه‌حل را پیاده‌سازی کنید، با دقت در مورد این معایب فکر کنید.
گزینه ۱: نوشتن گزارش‌های محلی در فضای ابری از یک فرآیند پس‌زمینه
با تغییر پیکربندی ثبت وقایع، می‌توان گزارش‌های کتابخانه کلاینت را در یک فایل محلی روی دستگاه شما نوشت. پس از اینکه گزارش‌ها در یک فایل محلی خروجی داده شدند، می‌توانید یک سرویس (daemon) برای جمع‌آوری گزارش‌ها و ارسال آنها به فضای ابری راه‌اندازی کنید.
یکی از محدودیت‌های این رویکرد این است که برخی از معیارهای عملکرد به طور پیش‌فرض ثبت نمی‌شوند. گزارش‌های کتابخانه کلاینت شامل جزئیاتی از اشیاء درخواست و پاسخ هستند، بنابراین معیارهای تأخیر شامل نمی‌شوند مگر اینکه تغییرات اضافی برای ثبت این موارد نیز ایجاد شود.
گزینه ۲: برنامه خود را روی Compute Engine اجرا کنید و Ops Agent را نصب کنید
اگر برنامه شما روی Compute Engine اجرا می‌شود، می‌توانید با نصب Ops Agent، گزارش‌های خود را به Google Cloud Logging ارسال کنید. Ops Agent را می‌توان طوری پیکربندی کرد که گزارش‌های برنامه شما را علاوه بر معیارها و گزارش‌هایی که به طور پیش‌فرض ارسال می‌شوند ، به Cloud Logging ارسال کند.
اگر برنامه شما در حال حاضر در محیط Google Cloud اجرا می‌شود، یا اگر قصد انتقال برنامه خود به Google Cloud را دارید، این گزینه بسیار خوبی برای بررسی است.
گزینه ۳: پیاده‌سازی لاگین در کد برنامه
ثبت وقایع مستقیماً از طریق کد برنامه می‌تواند به یکی از دو روش زیر انجام شود:
گنجاندن محاسبات معیارها و دستورات لاگ در هر مکان قابل اجرا در کد شما. این گزینه برای پایگاه‌های کد کوچکتر، که در آن هزینه‌های دامنه و نگهداری چنین تغییری حداقل خواهد بود، امکان پذیرتر است.
پیاده‌سازی یک رابط ثبت وقایع. اگر منطق برنامه بتواند به گونه‌ای انتزاعی شود که بخش‌های مختلف برنامه از یک کلاس پایه ارث‌بری کنند، منطق ثبت وقایع می‌تواند در آن کلاس پایه پیاده‌سازی شود. این گزینه معمولاً نسبت به گنجاندن دستورات ثبت وقایع در سراسر کد برنامه ترجیح داده می‌شود، زیرا نگهداری و مقیاس‌پذیری آن آسان‌تر است. برای پایگاه‌های کد بزرگتر، قابلیت نگهداری و مقیاس‌پذیری این راه‌حل اهمیت بیشتری دارد.
یکی از محدودیت‌های این رویکرد این است که گزارش‌های کامل درخواست و پاسخ از کد برنامه در دسترس نیستند. اشیاء کامل درخواست و پاسخ را می‌توان از طریق رهگیرهای gRPC دسترسی پیدا کرد؛ اینگونه است که کتابخانه کلاینت داخلی، گزارش‌های درخواست و پاسخ را دریافت می‌کند. در صورت بروز خطا، ممکن است اطلاعات اضافی در شیء استثنا در دسترس باشد، اما جزئیات کمتری برای پاسخ‌های موفق در منطق برنامه در دسترس است. به عنوان مثال، در بیشتر موارد، شناسه درخواست برای یک درخواست موفق از اشیاء پاسخ API گوگل ادز قابل دسترسی نیست.
گزینه ۴: پیاده‌سازی یک رهگیر ثبت وقایع gRPC سفارشی
gRPC از رهگیرهای تکی و جریانی پشتیبانی می‌کند که می‌توانند به اشیاء درخواست و پاسخ هنگام عبور بین کلاینت و سرور دسترسی داشته باشند. کتابخانه‌های کلاینت API گوگل ادز از رهگیرهای gRPC برای ارائه پشتیبانی داخلی از ثبت وقایع استفاده می‌کنند. به طور مشابه، شما می‌توانید یک رهگیر gRPC سفارشی را برای دسترسی به اشیاء درخواست و پاسخ، استخراج اطلاعات برای اهداف ثبت وقایع و نظارت و نوشتن آن داده‌ها در مکان مورد نظر خود پیاده‌سازی کنید.
برخلاف برخی از راه‌حل‌های دیگر ارائه شده در اینجا، پیاده‌سازی یک رهگیر gRPC سفارشی به شما انعطاف‌پذیری لازم برای ثبت اشیاء درخواست و پاسخ در هر درخواست و پیاده‌سازی منطق اضافی برای ثبت جزئیات درخواست را می‌دهد. به عنوان مثال، می‌توانید زمان سپری شده از یک درخواست را با پیاده‌سازی منطق زمان‌بندی عملکرد در خود رهگیر سفارشی محاسبه کنید، سپس معیار را در Google Cloud Logging ثبت کنید تا برای نظارت بر تأخیر در Google Cloud Monitoring در دسترس باشد.
رهگیر سفارشی ثبت وقایع گوگل کلود در پایتون
برای نشان دادن این راهکار، ما یک مثال از یک رهگیر ثبت وقایع سفارشی در پایتون نوشته‌ایم. رهگیر سفارشی ایجاد شده و به سرویس‌گیرنده ارسال می‌شود. سپس به اشیاء درخواست و پاسخی که در هر فراخوانی متد سرویس عبور می‌کنند، دسترسی پیدا می‌کند، داده‌های آن اشیاء را پردازش می‌کند و داده‌ها را به 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