Günlük kaydı ve izleme, uygulama performansını anlamanıza ve optimize etmenize, ayrıca hatalarla ve sistemle ilgili sorunlarla ilgili teşhisler yapmanıza yardımcı olmak için birlikte çalışır. Teknik desteğe ihtiyaç duyduğunuzda API çağrı günlüklerini sağlayabilmek için tüm API çağrıları için özet günlükleri ve başarısız API çağrıları için ayrıntılı günlükleri etkinleştirmeniz gerekir.
İstemci kitaplığı günlük kaydı
Google Ads API istemci kitaplıkları, yerleşik günlük kaydı özelliğine sahiptir. Platforma özgü günlük kaydı ayrıntıları için tercih ettiğiniz istemci kitaplığındaki günlük kaydı dokümanlarına bakın.
Günlük biçimi
Google Ads API istemci kitaplıkları, her API çağrısı için bir ayrıntılı günlük ve özet günlük oluşturur. Ayrıntılı günlük, API çağrısının tüm ayrıntılarını içerirken özet günlük, API çağrısının minimum ayrıntılarını içerir. Her günlük türüne ait bir örnek gösterilir. Günlükler, okunabilirlik için kısaltılır ve biçimlendirilir.
Özet günlüğü
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.")
Ayrıntılı günlük
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----------------
İstemci kitaplığı kullanmıyorsam ne olur?
İstemci kitaplığı kullanmıyorsanız giden ve gelen API çağrılarının ayrıntılarını yakalamak için kendi günlük kaydınızı uygulayın. En azından request-id yanıt başlığının değerini günlüğe kaydetmeniz gerekir. Bu değer, gerektiğinde teknik destek ekipleriyle paylaşılabilir.
Buluta günlük kaydı
Uygulamanızla ilgili günlükleri ve performans metriklerini yakalamak için kullanabileceğiniz birçok araç vardır. Örneğin, performans metriklerini Google Cloud Projenize kaydetmek için Google Cloud Logging'i kullanabilirsiniz. Bu sayede, günlüklenen metriklerden yararlanmak için Google Cloud Monitoring'de kontrol panelleri ve uyarılar oluşturabilirsiniz.
Cloud Logging, Perl hariç desteklenen tüm Google Ads API istemci kitaplığı dilleri için istemci kitaplıkları sunar. Bu nedenle, çoğu durumda Cloud Logging ile doğrudan istemci kitaplığı entegrasyonunuzdan günlük kaydı oluşturabilirsiniz. Cloud Logging, Perl dahil diğer diller için de REST API sunar.
Google Ads API istemci kitaplığından Cloud Logging'a veya başka bir araca günlük kaydı oluşturmak için birkaç seçenek vardır. Her seçeneğin uygulama süresi, karmaşıklığı ve performansı açısından kendi avantajları ve dezavantajları vardır. Hangi çözümü uygulayacağınıza karar vermeden önce bu değiş tokuşları dikkatlice düşünün.
1. seçenek: Arka plan işleminden yerel günlükleri buluta yazma
Günlük kaydı yapılandırmanızı değiştirerek istemci kitaplığı günlüklerini makinenizdeki yerel bir dosyaya yazabilirsiniz. Günlükler yerel bir dosyaya aktarıldıktan sonra, günlükleri toplayıp buluta gönderecek bir daemon oluşturabilirsiniz.
Bu yaklaşımın bir sınırlaması, bazı performans metriklerinin varsayılan olarak yakalanmamasıdır. İstemci kitaplığı günlükleri, istek ve yanıt nesnelerindeki ayrıntıları içerir. Bu nedenle, bunları da günlük kaydetmek için ek değişiklikler yapılmadığı sürece gecikme metrikleri dahil edilmez.
2. seçenek: Uygulamanızı Compute Engine'da çalıştırın ve İşlem Aracısı'nı yükleyin
Uygulamanız Compute Engine'da çalışıyorsa İşlem Aracısı'nı yükleyerek günlüklerinizi Google Cloud Logging'e gönderebilirsiniz. Ops Agent, varsayılan olarak gönderilen metrikler ve günlüklere ek olarak uygulama günlüklerinizi Cloud Logging'a gönderecek şekilde yapılandırılabilir.
Uygulamanız zaten bir Google Cloud ortamında çalışıyorsa veya uygulamanızı Google Cloud'a taşımayı düşünüyorsanız bu seçeneği değerlendirmenizi öneririz.
3. seçenek: Uygulama kodunuza günlük kaydı ekleyin
Doğrudan uygulama kodundan günlük kaydı iki şekilde yapılabilir:
Metrik hesaplamalarını ve günlük ifadelerini kodunuzdaki her uygun konuma dahil edin. Bu seçenek, bu tür bir değişikliğin kapsamının ve bakım maliyetlerinin minimum olacağı daha küçük kod tabanları için daha uygundur.
Günlük kaydı arayüzü uygulama Uygulama mantığı, uygulamanın farklı parçalarının aynı temel sınıftan devralacağı şekilde soyutlanabilirse günlük kaydı mantığı bu temel sınıfa uygulanabilir. Bu seçenek, bakımı ve ölçeklendirilmesi daha kolay olduğu için genellikle uygulama kodunda günlük ifadeleri dahil etmeye tercih edilir. Daha büyük kod tabanlarında bu çözümün sürdürülebilirliği ve ölçeklenebilirliği daha da önemlidir.
Bu yaklaşımın bir sınırlaması, istek ve yanıt günlüklerinin tamamının uygulama kodundan kullanılamamasıdır. Tam istek ve yanıt nesnelerine gRPC müdahalecilerinden erişilebilir. Yerleşik istemci kitaplığı günlükleri, istek ve yanıt günlüklerini bu şekilde elde eder. Hata durumunda, istisna nesnesinde ek bilgiler bulunabilir ancak uygulama mantığındaki başarılı yanıtlar için daha az ayrıntı mevcuttur. Örneğin, çoğu durumda başarılı bir istek için istek kimliğine Google Ads API yanıt nesnelerinden erişilemez.
4. Seçenek: Özel bir gRPC günlük kaydı aracısı uygulama
gRPC, istemci ile sunucu arasında geçiş yapan istek ve yanıt nesnelerine erişebilen tek bileşenli ve akış engelleyicileri destekler. Google Ads API istemci kitaplıkları, yerleşik günlük kaydı desteği sunmak için gRPC müdahalecileri kullanır. Benzer şekilde, istek ve yanıt nesnelerine erişmek, günlük kaydı ve izleme amacıyla bilgi ayıklamak ve bu verileri istediğiniz konuma yazmak için özel bir gRPC müdahalesi uygulayabilirsiniz.
Burada sunulan diğer çözümlerden bazılarının aksine, özel bir gRPC müdahaleci uygulamak size her istekte istek ve yanıt nesnelerini yakalama ve isteğin ayrıntılarını yakalamak için ek mantık uygulama esnekliği sağlar. Örneğin, performans zamanlama mantığını özel müdahalecinin içine uygulayarak bir isteğin geçen süresini hesaplayabilir, ardından metriği Google Cloud Monitoring'de gecikme izleme için kullanılabilir hale getirmek üzere Google Cloud Logging'a kaydedebilirsiniz.
Python'da özel Google Cloud Logging aracısı
Bu çözümü göstermek için Python'da özel günlük kaydı tutucu örneği yazdık. Özel müdahaleci oluşturulur ve hizmet istemciye iletilir. Ardından, her hizmet yöntemi çağrısında iletilen istek ve yanıt nesnelerine erişir, bu nesnelerdeki verileri işler ve verileri Google Cloud Logging'a gönderir.
Örnekte, istek ve yanıt nesnelerinden gelen verilere ek olarak, istek için geçen süreyi ve izleme amacıyla yararlı olabilecek diğer meta verileri (ör. istemin başarılı olup olmadığı) yakalamak için bazı ek mantıklar uygulanır. Bu bilgilerin hem genel olarak izleme için hem de özellikle Google Cloud Logging ve Google Cloud Monitoring'i birleştirirken nasıl yararlı olabileceği hakkında daha fazla bilgi için İzleme kılavuzuna göz atı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 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