Настройка ведения журналов

Клиентская библиотека .NET регистрирует запросы, ответы и сводные сообщения, отправленные в Google Ads API. Журналы можно записывать в пользовательский экземпляр TraceListener или ILogger.

TraceListener

Чтобы включить ведение журнала в TraceListener, добавьте следующие строки в метод Main перед вызовами 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);

ILogger

Если вы уже используете ILogger для журналов приложений, это решение позволит вам интегрировать журналы Google Ads API в существующую инфраструктуру ведения журналов.

Сначала создайте LoggerFactory или, если он у вас уже есть, добавьте фильтры для журналов 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);
});

Затем используйте LoggerFactory, чтобы создать регистраторы для сводок и подробных сведений о запросах и ответах:

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

Наконец, настройте клиентскую библиотеку так, чтобы она перенаправляла трассировки в ваши экземпляры ILogger:

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

Это решение позволяет интегрировать журналы запросов и ответов Google Ads API в существующие фреймворки ведения журналов, такие как Log4Net, NLog и Serilog.

Уровни ведения журнала

Библиотека регистрирует разные типы событий на разных уровнях журнала:

  • Успешный ответ API. Сводка регистрируется на уровне INFO, а полный запрос и ответ – на уровне DEBUG.
  • Ответ API с ошибкой. Сводное сообщение регистрируется в WARN, а полный запрос и ответ – в INFO.
  • Частичные сбои регистрируются в DEBUG.

Идентификатор запроса

В большинстве случаев журналы, созданные клиентской библиотекой, содержат достаточно информации для устранения неполадок. При обращении в службу поддержки предоставьте журналы (в которых по умолчанию скрыты конфиденциальные поля аутентификации) или идентификатор запроса, который регистрируется в журнале ответов.

Если вы хотите получать идентификатор запроса программным способом, используйте один из следующих подходов.

Извлечение из обычных унарных вызовов API

Вы можете использовать специальный CallSettings с 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);

Извлечение из вызовов API потоковой передачи

Идентификатор запроса возвращается как часть объекта ответа для вызовов API потоковой передачи. Например, идентификатор запроса для вызова SearchStream можно получить следующим образом:

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

Исключения

Идентификатор запроса возвращается как часть исключения GoogleAdsException при каждом сбое вызова API:

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

Настроить расширенное ведение журналов

Если в журнале API недостаточно информации, включите ведение журнала на более низком уровне – на уровне транспорта gRPC. Учтите, что выходные данные могут быть объемными.

При использовании стандартного транспорта Grpc.Net.Client настройте журналы на уровне транспорта с помощью поставщика ILogger .NET, добавив фильтр для категории Grpc (например, builder.AddFilter("Grpc", LogLevel.Debug)).

Если вы используете устаревший транспорт Grpc.Core (UseGrpcCore = true), по умолчанию журналы gRPC записываются в stderr. Вы также можете прикрепить собственный регистратор, как показано в следующем примере. Подробнее о поддерживаемых переменных среды gRPC…

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

Конфигурация TraceListener с помощью App.config (устаревший способ)

Если приложение создано для целевой платформы .NET Framework, вы можете загрузить конфигурацию ведения журнала из файла App.config или Web.config приложения. Это устаревшая функция .NET, которая не поддерживается для приложений, созданных для современных целевых платформ .NET.

Чтобы использовать эту функцию, добавьте в файл конфигурации следующие изменения:

  1. Добавьте следующий фрагмент в раздел <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. Добавьте следующий фрагмент в раздел <configSections>:

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

    В этом случае App.config будет выглядеть следующим образом:

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