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

ILogger

Se você já estiver usando um ILogger para os registros do aplicativo, essa solução permitirá integrar os registros da API Google Ads à infraestrutura de registro 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 registradores 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 rastros para as instâncias ILogger:

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

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

Níveis de registro

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

  • 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 completa e a resposta 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 problemas. Ao entrar em contato com o suporte, forneça os registros (que ocultam campos de autenticação confidenciais por padrão) ou compartilhe o ID da solicitação, que é registrado como parte do registro de resposta.

Se 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ções 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.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 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 gRPC. Lembre-se de que a saída pode ser volumosa.

Ao usar o transporte Grpc.Net.Client padrão, configure os registros de 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 gRPC serão gravados em stderr por padrão. Também é possível anexar seu próprio registrador, 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, você poderá carregar a configuração de registro 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" />

    Seu App.config será parecido com este:

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