Configurar a geração de registros

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

Atenção: embora a biblioteca de cliente oculte os tokens OAuth nos registros por padrão, os arquivos de registro ainda podem conter informações confidenciais de clientes e campanhas. Sempre restrinja as permissões de arquivo em diretórios em que os arquivos de registro são armazenados.

TraceListener

Para ativar a geração de registros em um TraceListener, adicione as seguintes linhas ao método Main antes de fazer chamadas de 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);

Observação: chame TraceUtilities.Configure apenas uma vez por ciclo de vida do aplicativo. O TraceListener criado é reutilizado automaticamente em todas as solicitações de API feitas pelo aplicativo. Não é necessário criar um novo para cada solicitação de API.

ILogger

Se você já usa um ILogger para os registros do aplicativo, essa solução permite integrar os registros da API Google Ads à sua infraestrutura de geração de registros.

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

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

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 traces para as instâncias do ILogger:

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

Com essa solução, é possível integrar os registros de solicitação de API e resposta da API Google Ads a frameworks de geração de registros, como Log4Net, NLog e Serilog.

Níveis de registro

A biblioteca registra diferentes tipos de eventos em diferentes níveis de registro:

• Resposta da API bem-sucedida: o resumo é registrado em INFO. A solicitação e a resposta completas são registradas em DEBUG.
• Resposta de erro da API: a mensagem de resumo é registrada em WARN. A solicitação e a resposta completas são registradas em INFO.
• Falhas parciais: 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 suporte, forneça os registros (que ocultam campos de autenticação sensíveis por padrão) ou compartilhe o ID da solicitação, que é registrado como parte do registro de resposta.

Se você preferir capturar o ID da solicitação de maneira programática, use uma das abordagens a seguir.

Extrair de chamadas de API unárias comuns

É possível usar um CallSettings personalizado com um TrailingMetadataHandler para capturar IDs de solicitação de chamadas unárias regulares:

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

Extrair de 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 receber o ID da solicitação para uma chamada SearchStream da seguinte maneira:

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

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;
    Console.WriteLine($"Failed Request ID: {requestId}");
}

Configurar a geração de registros avançada

Se o registro da API não fornecer detalhes suficientes, ative o registro de nível inferior no nível de transporte do gRPC. Lembre-se de que a saída pode ser volumosa.

Ao usar o transporte Grpc.Net.Client padrão, configure os registros no nível de transporte pelo provedor ILogger do .NET adicionando um filtro para a categoria Grpc (por exemplo, builder.AddFilter("Grpc", LogLevel.Debug)).

Se você estiver usando o transporte legado Grpc.Core (UseGrpcCore = true), os registros do gRPC serão gravados em stderr por padrão. Se preferir, anexe seu próprio logger, conforme mostrado no exemplo a seguir. Para mais detalhes, consulte as variáveis de ambiente gRPC 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, será possível carregar a configuração de geração de registros no arquivo App.config ou Web.config do app. Essa é uma funcionalidade legada do .NET que não é compatível com apps criados para destinos modernos do .NET.

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

1. Adicione o snippet abaixo 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 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. Adicione o snippet abaixo na 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>