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 um TraceListener personalizado ou em uma instância ILogger personalizada.

TraceListener

Para ativar o registro em um TraceListener, adicione as seguintes linhas 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,
    "logs/details.log",
    System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(
    TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "logs/summary.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 à sua infraestrutura de geração de registros atual.

Primeiro, crie um LoggerFactory ou, se já tiver um, adicione os filtros para 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 loggers de 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 rastreamentos às suas instâncias ILogger:

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

Com essa solução, é possível 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:

• Resposta bem-sucedida da API: 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 seus 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

Você pode 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 de uma chamada SearchStream da seguinte maneira:

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V25.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 o registro avançado

Se o registro da API não fornecer detalhes suficientes, ative o registro de nível inferior no nível de transporte do gRPC. O resultado pode ser extenso.

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 Grpc.Core legado (UseGrpcCore = true), os registros do gRPC serão gravados em stderr por padrão. Também é possível anexar 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 uma meta 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 modernos do .NET.

Para usar esse recurso, adicione as seguintes mudanças 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 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 a seguir 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>