Configurer la journalisation

La bibliothèque cliente .NET consigne les requêtes, les réponses et les messages récapitulatifs envoyés à l'API Google Ads. Les journaux peuvent être écrits dans un TraceListener personnalisé ou dans une instance ILogger personnalisée.

Attention : Bien que la bibliothèque cliente masque par défaut les jetons OAuth dans les journaux, les fichiers journaux peuvent toujours contenir des informations sensibles sur les clients et les campagnes. Limitez toujours les autorisations de fichiers sur les répertoires où sont stockés les fichiers journaux.

TraceListener

Vous pouvez activer la journalisation dans un TraceListener en ajoutant les lignes suivantes dans votre méthode Main avant d'effectuer des appels d'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);

Remarque : N'appelez TraceUtilities.Configure qu'une seule fois par cycle de vie de l'application. Le TraceListener qu'il crée est automatiquement réutilisé pour toutes les requêtes API effectuées par l'application. Vous n'avez pas besoin d'en créer un pour chaque requête API.

ILogger

Si vous utilisez déjà un ILogger pour les journaux de votre application, cette solution vous permet d'intégrer les journaux de l'API Google Ads à votre infrastructure de journalisation existante.

Commencez par créer un LoggerFactory ou, si vous en avez déjà un, ajoutez les filtres pour les journaux de l'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);
});

Ensuite, utilisez LoggerFactory pour créer des enregistreurs pour les résumés et les détails des requêtes et des réponses :

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

Enfin, configurez la bibliothèque cliente pour rediriger ses traces vers vos instances ILogger :

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

Cette solution vous permet d'intégrer les journaux de requêtes et de réponses de l'API Google Ads dans des frameworks de journalisation existants, tels que Log4Net, NLog et Serilog.

Niveaux de journalisation

La bibliothèque consigne différents types d'événements à différents niveaux de journalisation :

• Réponse de l'API réussie : le résumé est consigné dans INFO, et la requête et la réponse complètes sont consignées dans DEBUG.
• Réponse d'erreur de l'API : le message récapitulatif est consigné au niveau WARN ; la requête et la réponse complètes sont consignées au niveau INFO.
• Échecs partiels : consignés dans DEBUG.

Identifiant de la demande

Dans la plupart des cas, les journaux générés par la bibliothèque cliente fournissent suffisamment d'informations pour résoudre vos problèmes. Lorsque vous contactez l'assistance, fournissez les journaux (qui masquent par défaut les champs d'authentification sensibles) ou partagez l'ID de la requête, qui est consigné dans le journal de réponse.

Si vous préférez capturer l'ID de requête de manière automatisée, utilisez l'une des approches suivantes.

Extraire des appels d'API unaires ordinaires

Vous pouvez utiliser un CallSettings personnalisé avec un TrailingMetadataHandler pour capturer les ID de requête des appels unaires standards :

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

Extraire des appels d'API de streaming

L'ID de requête est renvoyé dans l'objet de réponse pour les appels d'API en streaming. Par exemple, vous pouvez obtenir l'ID de requête pour un appel SearchStream comme suit :

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

Exceptions

L'ID de requête est renvoyé dans l'exception GoogleAdsException chaque fois qu'un appel d'API échoue :

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

Configurer la journalisation avancée

Si le journal de l'API ne vous fournit pas suffisamment de détails, activez la journalisation de niveau inférieur au niveau du transport gRPC. N'oubliez pas que le résultat peut être volumineux.

Lorsque vous utilisez le transport Grpc.Net.Client par défaut, configurez les journaux au niveau du transport via le fournisseur ILogger de .NET en ajoutant un filtre pour la catégorie Grpc (par exemple, builder.AddFilter("Grpc", LogLevel.Debug)).

Si vous utilisez l'ancien transport Grpc.Core (UseGrpcCore = true), les journaux gRPC sont écrits dans stderr par défaut. Vous pouvez également associer votre propre enregistreur, comme illustré dans l'exemple suivant. Pour en savoir plus, consultez les variables d'environnement gRPC compatibles.

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

Configuration de TraceListener à l'aide d'App.config (ancienne méthode)

Si votre application est compilée pour une cible .NET Framework, vous pouvez charger la configuration de journalisation à partir du fichier App.config ou Web.config de votre application. Il s'agit d'une ancienne fonctionnalité .NET qui n'est pas compatible avec les applications conçues pour les cibles .NET modernes.

Pour utiliser cette fonctionnalité, ajoutez les modifications suivantes à votre fichier de configuration :

1. Ajoutez l'extrait suivant sous la section <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. Ajoutez l'extrait suivant sous la section <configSections> :

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

   Votre App.config se présente alors comme suit :

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