Configurazione logging

La libreria client .NET registra le richieste, le risposte e i messaggi di riepilogo inviati all'API Google Ads. I log possono essere scritti in un TraceListener personalizzato o in un'istanza ILogger personalizzata.

TraceListener

Puoi attivare la registrazione in un TraceListener aggiungendo le seguenti righe nel metodo Main prima di effettuare chiamate 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 utilizzi già un ILogger per i log delle applicazioni, questa soluzione ti consente di integrare i log dell'API Google Ads nell'infrastruttura di logging esistente.

Innanzitutto, crea un LoggerFactory o, se ne hai già uno, aggiungi i filtri per i log dell'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);
});

Quindi, utilizza LoggerFactory per creare logger per i riepiloghi e i dettagli delle richieste e delle risposte:

ILogger summaryLogger = loggerFactory.CreateLogger(
    TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE);
ILogger detailLogger = loggerFactory.CreateLogger(
    TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE);

Infine, configura la libreria client in modo che reindirizzi le tracce alle istanze ILogger:

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

Questa soluzione ti consente di integrare i log delle richieste e delle risposte dell'API Google Ads nei framework di logging esistenti, come Log4Net, NLog e Serilog.

Livelli di log

La libreria registra diversi tipi di eventi a diversi livelli di log:

  • Risposta dell'API riuscita: il riepilogo viene registrato a livello INFO; la richiesta e la risposta complete vengono registrate a livello DEBUG.
  • Risposta di errore dell'API: il messaggio di riepilogo viene registrato a livello WARN; la richiesta completa e la risposta vengono registrate a livello INFO.
  • Errori parziali: registrati a livello DEBUG.

ID richiesta

Nella maggior parte dei casi, i log generati dalla libreria client forniscono dettagli sufficienti per risolvere i problemi. Quando contatti l'assistenza , fornisci i log (che redigono i campi di autenticazione sensibili per impostazione predefinita) o condividi l'ID richiesta, che viene registrato come parte del log di risposta.

Se preferisci acquisire l'ID richiesta a livello di programmazione, utilizza uno dei seguenti approcci.

Estrai dalle normali chiamate API unarie

Puoi utilizzare un CallSettings personalizzato con un TrailingMetadataHandler per acquisire gli ID richiesta dalle normali chiamate unarie:

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

Estrai dalle chiamate API di streaming

L'ID richiesta viene restituito come parte dell'oggetto di risposta per le chiamate API di streaming. Ad esempio, puoi ottenere l'ID richiesta per una chiamata SearchStream come segue:

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

Eccezioni

L'ID richiesta viene restituito come parte dell'eccezione GoogleAdsException ogni volta che una chiamata API non va a buon fine:

try
{
    // Make an API call.
}
catch (GoogleAdsException e)
{
    string requestId = e.RequestId;
    Console.WriteLine($"Failed Request ID: {requestId}");
}

Configura la registrazione avanzata

Se il log dell'API non fornisce dettagli sufficienti, attiva la registrazione di livello inferiore a livello di trasporto gRPC. Tieni presente che l'output può essere voluminoso.

Quando utilizzi il trasporto Grpc.Net.Client predefinito, configura i log a livello di trasporto tramite il provider ILogger di .NET aggiungendo un filtro per la categoria Grpc (ad esempio, builder.AddFilter("Grpc", LogLevel.Debug)).

Se utilizzi il trasporto Grpc.Core legacy (UseGrpcCore = true), i log gRPC vengono scritti in stderr per impostazione predefinita oppure puoi collegare il tuo logger come mostrato nell'esempio seguente. Per maggiori dettagli, consulta le variabili di ambiente gRPC supportate.

Environment.SetEnvironmentVariable("GRPC_VERBOSITY", "DEBUG");
Environment.SetEnvironmentVariable("GRPC_TRACE", "http");
GrpcEnvironment.SetLogger(new ConsoleLogger());

Configurazione di TraceListener utilizzando App.config (legacy)

Se la tua app viene creata per una destinazione .NET Framework, puoi caricare la configurazione di logging dal file App.config o Web.config dell'app. Si tratta di una funzionalità .NET legacy non supportata per le app create per le destinazioni .NET moderne.

Per utilizzare questa funzionalità, aggiungi le seguenti modifiche al file di configurazione:

  1. Aggiungi il seguente snippet nella sezione <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. Aggiungi il seguente snippet nella sezione <configSections>:

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

    Il file App.config avrà il seguente aspetto:

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