Skonfiguruj logowanie

Biblioteka klienta .NET rejestruje żądania, odpowiedzi i komunikaty podsumowujące wysyłane do interfejsu Google Ads API. Logi mogą być zapisywane w niestandardowej instancji TraceListener lub ILogger.

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

TraceListener

Możesz włączyć logowanie do TraceListener, dodając te wiersze w metodzie Main przed wywołaniem 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łaj TraceUtilities.Configure tylko raz w cyklu życia aplikacji. Utworzony obiekt TraceListener jest automatycznie używany we wszystkich żądaniach do interfejsu API wysyłanych przez aplikację. Nie musisz tworzyć nowego obiektu dla każdego żądania do interfejsu API.

ILogger

Jeśli używasz już ILogger do obsługi logów aplikacji, to rozwiązanie umożliwia integrację logów interfejsu Google Ads API z istniejącą infrastrukturą logowania.

Najpierw utwórz LoggerFactory, a jeśli już go 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 metody LoggerFactory, aby utworzyć obiekty logujące dla podsumowań i szczegółów żądań i odpowiedzi:

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

Na koniec skonfiguruj bibliotekę klienta, aby przekierowywała logi czasu do instancji ILogger:

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

To rozwiązanie umożliwia integrację logów żądań do interfejsu API i odpowiedzi interfejsu Google Ads API z istniejącymi 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ź są rejestrowane na poziomie DEBUG.
• Odpowiedź interfejsu API z błędem: podsumowanie jest rejestrowane w WARN, a pełne żądanie i odpowiedź – w INFO.
• Częściowe niepowodzenia: zarejestrowane o DEBUG.

Identyfikator żądania

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

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

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

Możesz użyć niestandardowego CallSettings z TrailingMetadataHandler, aby przechwytywać identyfikatory żądań ze zwykłych wywołań jednoargumentowych:

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 strumieniowania

Identyfikator żądania jest zwracany jako część obiektu odpowiedzi w przypadku wywołań interfejsu API do strumieniowego przesyłania danych. Możesz na przykład uzyskać identyfikator żądania dla wywołania SearchStream 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, gdy wywołanie interfejsu API się nie powiedzie:

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

Konfigurowanie zaawansowanego logowania

Jeśli dziennik interfejsu API nie zawiera wystarczającej ilości szczegółów, włącz logowanie na niższym poziomie na poziomie transportu gRPC. Pamiętaj, że dane wyjściowe mogą być bardzo 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 starszej wersji transportu Grpc.Core (UseGrpcCore = true), logi gRPC są domyślnie zapisywane w stderr. Możesz też dołączyć własny logger, jak pokazano w przykładzie poniżej. Więcej informacji znajdziesz w artykule o obsługiwanych zmiennych środowiskowych gRPC.

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

Konfiguracja TraceListener przy użyciu pliku App.config (starsza wersja)

Jeśli aplikacja jest kompilowana dla platformy .NET Framework, możesz wczytać konfigurację logowania z pliku App.config lub Web.config aplikacji. Jest to starsza funkcja .NET, która nie jest obsługiwana w przypadku aplikacji utworzonych dla nowoczesnych środowisk docelowych .NET.

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

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" />
   

   App.config wygląda więc 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>