Logging

A biblioteca de cliente do .NET registra solicitações, respostas e mensagens de resumo feitas para a API Google Ads. Os registros podem ser gravados em um TraceListener personalizado ou em uma instância ILogger personalizada.

TraceListener

É possível ativar o registro em um TraceListener adicionando a linha a seguir ao método Main antes de fazer chamadas de API.

using Google.Ads.GoogleAds.Util;
...

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

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "C:\\logs\\details.log", System.Diagnostics.SourceLevels.All);

ILogger

Se você já usa um ILogger para os registros do aplicativo, essa solução permite integrar os registros da API Google Ads aos registros atuais.

Primeiro, crie um LoggerFactory ou, se você já tiver um, adicione os filtros para os registros da API Google Ads:

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

Em seguida, use o LoggerFactory para criar registradores para resumos e detalhes de solicitações e respostas:

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

Por fim, configure a biblioteca de cliente para redirecionar os rastros para as instâncias ILogger:

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

Essa solução permite integrar os registros de solicitação e resposta da API Google Ads a frameworks de registro existentes, como Log4Net, NLog e Serilog.

Níveis de registro

A biblioteca registra diferentes tipos de eventos em diferentes níveis de registro. Para uma resposta de API bem-sucedida, o resumo é registrado em INFO, e a solicitação completa e as respostas são registradas em DEBUG.

Em uma solicitação que resulta em um erro de API, a mensagem de resumo é registrada em WARN, e a solicitação e a resposta completas são registradas em INFO.

As falhas parciais são registradas em DEBUG.

ID da solicitação

Na maioria dos casos, os registros gerados pela biblioteca de cliente fornecem detalhes suficientes para resolver os problemas. Ao entrar em contato com o fórum/pseudônimos de suporte, você pode fornecer os registros (que ocultam informações sensíveis por padrão) ou apenas compartilhar o ID da solicitação (que é registrado como parte do registro de resposta).

Se você preferir capturar o ID de solicitação, use uma das seguintes abordagens:

Extração por chamadas de API comuns

É possível usar um CallSetting personalizado com um TrailingMetadataHandler para capturar IDs de solicitação de chamadas unárias normais.

CallSettings callSettings = CallSettings.FromTrailingMetadataHandler(
    delegate (Metadata metadata) {
        // Extract the request ID from the trailing metadata.
        string requestId = metadata.Get("request-id").Value;
    });
// Add the campaigns.
MutateCampaignsResponse retVal = campaignService.MutateCampaigns(
    customerId.ToString(), operations.ToArray(), callSettings);

Extração por chamadas de API de streaming

O ID da solicitação é retornado como parte do objeto de resposta para chamadas da API Streaming. Por exemplo, é possível receber o ID de solicitação de uma chamada SearchStream da seguinte maneira:

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V19.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,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        // Extract the request ID from the response.
        string requestId = resp.RequestId;
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
        }
    }
);

Exceções

O ID da solicitação é retornado como parte da exceção GoogleAdsException sempre que uma chamada de API falha.

try
{
  // Make an API call.
  ...
}
catch (GoogleAdsException e)
{
    string requestId = e.RequestId;
}

Geração de registros avançada

Se o registro da API não fornecer detalhes suficientes, ative mais registros de nível baixo no nível do gRPC. Lembre-se de que a saída pode ser volumosa. Os registros do gRPC são gravados no stderr, mas você pode anexar seu próprio registrador, conforme mostrado abaixo. Variáveis de ambiente compatíveis.

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

Configuração do TraceListener usando o App.config (legado)

Se o app for criado para um destino do .NET Framework, será possível carregar a configuração de registro do arquivo App.config ou Web.config do app. Essa é uma funcionalidade legada do .NET que não tem suporte para apps criados para destinos do .NET Core.

Para usar esse recurso, adicione as seguintes mudanças ao arquivo de configuração:

  1. Adicione o snippet abaixo à seção <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 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 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 Ads* .NET libraries. The default is level is set to
         Warning. To disable all messages, set this value to Off. See
         msdn.microsoft.com/en-us/library/system.diagnostics.sourcelevels.aspx
         for all possible values this key can take. -->
    <add name="GoogleAds.DeprecationMessages" value="Warning"/>
    <!-- Use this trace switch to control the detailed request logs written by 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
         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. Adicione o snippet abaixo à seção <configSections>.

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

    O App.config vai ficar assim:

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