Định cấu hình ghi nhật ký

Thư viện ứng dụng .NET ghi lại các yêu cầu, phản hồi và thông báo tóm tắt được gửi đến Google Ads API. Bạn có thể ghi nhật ký vào TraceListener tuỳ chỉnh hoặc vào một phiên bản ILogger tuỳ chỉnh.

TraceListener

Bạn có thể bật tính năng ghi nhật ký vào TraceListener bằng cách thêm các dòng sau vào phương thức Main trước khi thực hiện bất kỳ lệnh gọi API nào:

using Google.Ads.GoogleAds.Util;

// Detailed logs.
TraceUtilities.Configure(
    TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "logs/details.log",
    System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(
    TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "logs/summary.log",
    System.Diagnostics.SourceLevels.All);

ILogger

Nếu bạn đang sử dụng ILogger cho nhật ký ứng dụng, thì giải pháp này cho phép bạn tích hợp nhật ký Google Ads API vào cơ sở hạ tầng ghi nhật ký hiện có.

Trước tiên, hãy tạo một LoggerFactory hoặc nếu bạn đã có một, hãy thêm các bộ lọc cho nhật ký API Google Ads:

var loggerFactory = LoggerFactory.Create(builder =>
{
    // Log to stdout.
    builder.AddConsole();
    builder.AddFilter(
        TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE, LogLevel.Trace);
    builder.AddFilter(
        TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE, LogLevel.Trace);
});

Sau đó, hãy dùng LoggerFactory để tạo trình ghi nhật ký cho các bản tóm tắt và thông tin chi tiết về yêu cầu và phản hồi:

ILogger summaryLogger = loggerFactory.CreateLogger(
    TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE);
ILogger detailLogger = loggerFactory.CreateLogger(
    TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE);

Cuối cùng, hãy định cấu hình thư viện ứng dụng để chuyển hướng các dấu vết của thư viện đến các thực thể ILogger:

TraceUtilities.ConfigureSummaryLogger(summaryLogger);
TraceUtilities.ConfigureDetailLogger(detailLogger);

Giải pháp này cho phép bạn tích hợp nhật ký yêu cầu và phản hồi của Google Ads API vào các khung ghi nhật ký hiện có, chẳng hạn như Log4Net, NLog và Serilog.

Các cấp độ nhật ký

Thư viện này ghi nhật ký nhiều loại sự kiện ở nhiều cấp độ nhật ký:

• Phản hồi API thành công: Thông tin tóm tắt được ghi vào nhật ký tại INFO; yêu cầu và phản hồi đầy đủ được ghi vào nhật ký tại DEBUG.
• Phản hồi lỗi API: Thông báo tóm tắt được ghi vào nhật ký tại WARN; yêu cầu và phản hồi đầy đủ được ghi vào nhật ký tại INFO.
• Không thực hiện được một phần: Đã ghi nhật ký tại DEBUG.

Mã yêu cầu

Trong hầu hết các trường hợp, nhật ký do thư viện ứng dụng tạo ra sẽ cung cấp đủ thông tin chi tiết để khắc phục các vấn đề của bạn. Khi bạn liên hệ với nhóm hỗ trợ, hãy cung cấp nhật ký (theo mặc định, nhật ký sẽ che đi các trường xác thực nhạy cảm) hoặc chia sẻ mã yêu cầu được ghi lại trong nhật ký phản hồi.

Nếu bạn muốn ghi lại mã yêu cầu theo phương thức lập trình, hãy sử dụng một trong các phương pháp sau.

Trích xuất từ các lệnh gọi API đơn nguyên thông thường

Bạn có thể sử dụng CallSettings tuỳ chỉnh với TrailingMetadataHandler để ghi lại mã yêu cầu từ các lệnh gọi đơn nguyên thông thường:

CallSettings callSettings = CallSettings.FromTrailingMetadataHandler(
    metadata =>
    {
        // Extract and log the request ID from the trailing metadata.
        string requestId = metadata.Get("request-id")?.Value;
        Console.WriteLine($"Request ID: {requestId}");
    });
// Add the campaigns.
MutateCampaignsResponse retVal = campaignService.MutateCampaigns(
    customerId.ToString(), operations.ToArray(), callSettings);

Trích xuất từ lệnh gọi API truyền trực tuyến

Mã yêu cầu được trả về trong đối tượng phản hồi cho các lệnh gọi API truyền phát trực tiếp. Ví dụ: bạn có thể nhận mã yêu cầu cho lệnh gọi SearchStream như sau:

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V25.GoogleAdsService);

// Retrieve all campaigns.
string query = @"SELECT
                campaign.id,
                campaign.name,
                campaign.network_settings.target_content_network
            FROM campaign
            ORDER BY campaign.id";

// Issue a search request.
googleAdsService.SearchStream(
    customerId.ToString(),
    query,
    (SearchGoogleAdsStreamResponse resp) =>
    {
        // Extract the request ID from the response.
        string requestId = resp.RequestId;
        Console.WriteLine($"Request ID: {requestId}");
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            Console.WriteLine(
                "Campaign with ID {0} and name '{1}' was found.",
                googleAdsRow.Campaign.Id,
                googleAdsRow.Campaign.Name);
        }
    }
);

Ngoại lệ

Mã yêu cầu được trả về trong ngoại lệ GoogleAdsException bất cứ khi nào một lệnh gọi API không thành công:

try
{
    // Make an API call.
}
catch (GoogleAdsException e)
{
    string requestId = e.RequestId;
    Console.WriteLine($"Failed Request ID: {requestId}");
}

Định cấu hình tính năng ghi nhật ký nâng cao

Nếu nhật ký API không cung cấp cho bạn đủ thông tin chi tiết, hãy bật tính năng ghi nhật ký ở cấp thấp hơn tại cấp truyền tải gRPC. Xin lưu ý rằng đầu ra có thể rất lớn.

Khi sử dụng phương thức truyền tải Grpc.Net.Client mặc định, hãy định cấu hình nhật ký cấp phương thức truyền tải thông qua trình cung cấp ILogger của .NET bằng cách thêm một bộ lọc cho danh mục Grpc (ví dụ: builder.AddFilter("Grpc", LogLevel.Debug)).

Nếu đang sử dụng phương thức truyền tải Grpc.Core cũ (UseGrpcCore = true), thì nhật ký gRPC sẽ được ghi vào stderr theo mặc định, hoặc bạn có thể đính kèm trình ghi nhật ký của riêng mình như minh hoạ trong ví dụ sau. Để biết thêm thông tin chi tiết, hãy xem các biến môi trường gRPC được hỗ trợ.

Environment.SetEnvironmentVariable("GRPC_VERBOSITY", "DEBUG");
Environment.SetEnvironmentVariable("GRPC_TRACE", "http");
GrpcEnvironment.SetLogger(new ConsoleLogger());

Cấu hình TraceListener bằng App.config (cũ)

Nếu ứng dụng của bạn tạo cho mục tiêu .NET Framework, bạn có thể tải cấu hình ghi nhật ký từ tệp App.config hoặc Web.config của ứng dụng. Đây là một chức năng .NET cũ không được hỗ trợ cho các ứng dụng được tạo cho các mục tiêu .NET hiện đại.

Để sử dụng tính năng này, hãy thêm các thay đổi sau vào tệp cấu hình:

1. Thêm đoạn mã sau vào phần <configuration>:

   <system.diagnostics>
     <sources>
       <source name="GoogleAds.DeprecationMessages"
           switchName="GoogleAds.DeprecationMessages"
           switchType="System.Diagnostics.SourceSwitch">
         <listeners>
           <add name="myListener"
                type="System.Diagnostics.EventLogTraceListener"
                initializeData="Application" />
         </listeners>
       </source>
       <source name="GoogleAds.DetailedRequestLogs"
           switchName="GoogleAds.DetailedRequestLogs"
           switchType="System.Diagnostics.SourceSwitch">
         <listeners>
           <add name="detailedRequestLogListener"
                type="System.Diagnostics.ConsoleTraceListener"
                initializeData="true" />
           <!-- Use the following to log to a file. Modify the initializeData
                attribute to control the path to the detailed request log
                file. -->
           <!--
           <add name="detailedRequestLogListener"
                type="System.Diagnostics.TextWriterTraceListener"
                initializeData="C:\Logs\detailed_logs.log" />
           <remove name="Default" />
           -->
         </listeners>
       </source>
       <source name="GoogleAds.SummaryRequestLogs"
           switchName="GoogleAds.SummaryRequestLogs"
           switchType="System.Diagnostics.SourceSwitch">
         <listeners>
           <add name="summaryRequestLogListener"
                type="System.Diagnostics.ConsoleTraceListener"
                initializeData="true" />
           <!-- Use the following to log to a file. Modify the initializeData
                attribute to control the path to the summary request log
                file. -->
           <!--
           <add name="summaryRequestLogListener"
                type="System.Diagnostics.TextWriterTraceListener"
                initializeData="C:\Logs\summary_logs.log" />
           -->
           <remove name="Default" />
         </listeners>
       </source>
     </sources>
     <switches>
       <!-- Use this trace switch to control the deprecation trace messages
            written by Google Ads .NET libraries. The default level is set to
            Warning. To disable all messages, set this value to Off. -->
       <add name="GoogleAds.DeprecationMessages" value="Warning" />
       <!-- Use this trace switch to control the detailed request logs written
            by Google Ads .NET libraries. The default level is set to Off.
            Logs are generated at both the Error and Information levels. -->
       <add name="GoogleAds.DetailedRequestLogs" value="Off" />
       <!-- Use this trace switch to control the summary request logs written
            by Google Ads .NET libraries. The default level is set to Off.
            Logs are generated at both the Error and Information levels. -->
       <add name="GoogleAds.SummaryRequestLogs" value="Off" />
     </switches>
     <trace autoflush="true" />
   </system.diagnostics>
   

2. Thêm đoạn mã sau vào phần <configSections>:

   <section name="system.diagnostics"
            type="System.Diagnostics.SystemDiagnosticsSection" />
   

   Khi đó, App.config của bạn sẽ có dạng như sau:

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <configSections>
       <section name="GoogleAdsApi"
                type="System.Configuration.DictionarySectionHandler" />
       <section name="system.diagnostics"
                type="System.Diagnostics.SystemDiagnosticsSection" />
     </configSections>
     <GoogleAdsApi>
       <!-- Google Ads API settings. -->
     </GoogleAdsApi>
     <system.diagnostics>
       <!-- Logging settings. -->
     </system.diagnostics>
   </configuration>