Skonfiguruj logowanie

Biblioteka klienta .NET rejestruje żądania, odpowiedzi i wiadomości podsumowujące wysyłane do interfejsu Google Ads API. Logi można zapisywać w niestandardowym TraceListener lub w niestandardowej ILogger instancji.

Uwaga: chociaż biblioteka klienta domyślnie usuwa tokeny protokołu OAuth w dziennikach, pliki dziennika mogą nadal zawierać poufne informacje o klientach i kampaniach. Zawsze ograniczaj uprawnienia do plików w katalogach, w których są przechowywane pliki dziennika.

TraceListener

Aby włączyć rejestrowanie w elemencie TraceListener, dodaj te wiersze do metody Main przed wykonaniem jakichkolwiek wywołań interfejsu API:

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);

Uwaga: wywołuj TraceUtilities.Configure tylko raz w cyklu życia aplikacji. Utworzony przez nią element TraceListener jest automatycznie używany we wszystkich żądaniach do interfejsu API wysyłanych przez aplikację. Nie musisz tworzyć nowego elementu dla każdego żądania do interfejsu API.

ILogger

Jeśli używasz już elementu ILogger do logów aplikacji, to rozwiązanie umożliwia zintegrowanie logów interfejsu Google Ads API z dotychczasową infrastrukturą logowania.

Najpierw utwórz element LoggerFactory lub, jeśli go już masz, dodaj filtry logów interfejsu Google Ads API:

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);
});

Następnie użyj elementu LoggerFactory, aby utworzyć rejestratory logów podsumowań i szczegółów żądań oraz odpowiedzi:

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

Na koniec skonfiguruj bibliotekę klienta tak, aby przekierowywała ślady do instancji ILogger:

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

To rozwiązanie umożliwia zintegrowanie dzienników żądań do interfejsu API i odpowiedzi interfejsu Google Ads API z dotychczasowymi platformami logowania, takimi jak Log4Net, NLog i Serilog.

Poziomy logowania

Biblioteka rejestruje różne typy zdarzeń na różnych poziomach logowania:

• Prawidłowa odpowiedź interfejsu API: podsumowanie jest rejestrowane na poziomie INFO, a pełne żądanie i odpowiedź – na poziomie DEBUG.
• Odpowiedź interfejsu API z błędem: wiadomość podsumowująca jest rejestrowana na poziomie WARN, a pełne żądanie i odpowiedź – na poziomie INFO.
• Częściowe błędy: rejestrowane na poziomie DEBUG.

Identyfikator żądania

W większości przypadków logi generowane przez bibliotekę klienta zawierają wystarczające szczegóły, aby rozwiązać problemy. Gdy skontaktujesz się z zespołem pomocy, podaj logi (które domyślnie redagują poufne pola uwierzytelniania) lub udostępnij identyfikator żądania, który jest rejestrowany jako część logu odpowiedzi.

Jeśli wolisz programowo przechwytywać identyfikator żądania, użyj jednej z tych metod.

Wyodrębnianie ze zwykłych wywołań interfejsu API

Aby przechwytywać identyfikatory żądań ze zwykłych wywołań jednoargumentowych, możesz użyć niestandardowego elementu CallSettings z elementem TrailingMetadataHandler:

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);

Wyodrębnianie z wywołań interfejsu API przesyłania strumieniowego

Identyfikator żądania jest zwracany jako część obiektu odpowiedzi w przypadku wywołań interfejsu API przesyłania strumieniowego. Na przykład identyfikator żądania wywołania SearchStream możesz uzyskać w ten sposób:

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V26.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);
        }
    }
);

Wyjątki

Identyfikator żądania jest zwracany jako część wyjątku GoogleAdsException za każdym razem, gdy wywołanie interfejsu API nie powiedzie się:

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

Konfigurowanie zaawansowanego logowania

Jeśli log interfejsu API nie zawiera wystarczających szczegółów, włącz logowanie na niższym poziomie w warstwie transportu gRPC. Pamiętaj, że dane wyjściowe mogą być obszerne.

Jeśli używasz domyślnego transportu Grpc.Net.Client, skonfiguruj logi na poziomie transportu za pomocą dostawcy ILogger platformy .NET, dodając filtr dla kategorii Grpc (np. builder.AddFilter("Grpc", LogLevel.Debug)).

Jeśli używasz starszego transportu Grpc.Core (UseGrpcCore = true), logi gRPC są domyślnie zapisywane w stderr. Możesz też dołączyć własny rejestrator logów, jak pokazano w tym przykładzie. Więcej informacji znajdziesz w artykule Obsługiwane zmienne środowiskowe gRPC.

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

Konfiguracja TraceListener za pomocą pliku App.config (starsza wersja)

Jeśli Twoja aplikacja jest tworzona na platformie .NET Framework, możesz wczytać konfigurację logowania z pliku App.config lub Web.config aplikacji. Jest to starsza funkcja platformy .NET, która nie jest obsługiwana w przypadku aplikacji tworzonych na nowoczesnych platformach .NET.

Aby korzystać z tej funkcji, wprowadź te zmiany w pliku konfiguracyjnym:

1. Dodaj ten fragment kodu w sekcji <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. Dodaj ten fragment kodu w sekcji <configSections>:

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

   Plik App.config będzie wyglądać tak:

   <?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>