Geração de registros

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

TraceListener

É possível ativar a geração de registros para um TraceListener adicionando a seguinte linha ao método Main antes de fazer qualquer chamada 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á estiver usando um ILogger para os registros do aplicativo, essa solução permitirá integrar os registros da API Google Ads aos registros atuais.

Primeiro, crie um LoggerFactory. 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 a fim de criar loggers para resumos e detalhes de solicitação e resposta:

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 traces 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 geração de registros atuais, 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 e as respostas completas 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 solucionar seus problemas. Ao entrar em contato com os alias/fórum de suporte, forneça os registros (que editam informações confidenciais por padrão) ou apenas compartilhe o ID da solicitação (que é registrado como parte do registro de resposta).

Se você preferir capturar o ID da solicitação por conta própria, 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 regulares.

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 de API de streaming. Por exemplo, é possível conseguir o ID da solicitação para uma chamada SearchStream desta maneira:

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V16.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 a geração de registros de nível mais baixo no nível do gRPC. Lembre-se de que a saída pode ser volumosa. Os registros gRPC são gravados em stderr, mas você pode anexar seu próprio logger, 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 App.config (legado)

Se o app for criado para um destino do .NET Framework, você poderá carregar a configuração de geração de registros do arquivo App.config ou Web.config do app. Essa é uma funcionalidade legada do .NET que não é compatível com apps criados para destinos do .NET Core.

Para usar esse recurso, é preciso adicionar as seguintes alterações ao arquivo de configuração:

1. Adicione o snippet a seguir na 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 a seguir na seção <configSections>.

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

   O App.config 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>