Logging

A biblioteca de cliente .NET registra solicitações, respostas e mensagens de resumo feitas à API Google Ads. Os registros podem ser gravados em um gerador de registros padrão na biblioteca .NET ou em um TraceListener personalizado.

Configuração

Ative a geração de registros adicionando a seguinte linha 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);

Configuração usando App.config (legado)

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

Para usar esse recurso, adicione as seguintes mudanças ao seu 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"/>
    

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

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 completa são registradas em INFO.

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 os problemas. Ao acessar o fórum de suporte/aliases, você pode disponibilizar os registros, que editam informações confidenciais por padrão, ou apenas compartilhar o ID da solicitação, que é registrado como parte do registro de respostas.

Se 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 código da solicitação é retornado como parte do objeto de resposta para chamadas da API de streaming. Por exemplo, é possível receber o ID da solicitação para uma chamada SearchStream desta maneira:

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V11.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 baixo nível no nível gRPC. A saída pode ser volumosa. Os registros de gRPC são gravados em 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());