Logging konfigurieren

In der .NET-Clientbibliothek werden Anfragen, Antworten und Zusammenfassungen protokolliert, die an die Google Ads API gesendet werden. Die Logs können in eine benutzerdefinierte TraceListener oder in eine benutzerdefinierte ILogger-Instanz geschrieben werden.

Achtung: Obwohl die Clientbibliothek OAuth-Tokens in Logs standardmäßig unkenntlich macht, können Logdateien dennoch vertrauliche Kunden- und Kampagneninformationen enthalten. Schränken Sie die Dateiberechtigungen für Verzeichnisse, in denen Logdateien gespeichert werden, immer ein.

TraceListener

Sie können das Logging in einer TraceListener aktivieren, indem Sie die folgenden Zeilen in Ihre Main-Methode einfügen, bevor Sie API-Aufrufe ausführen:

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

Hinweis: Rufen Sie TraceUtilities.Configure nur einmal pro Anwendungslebenszyklus auf. Die von ihr erstellte TraceListener wird automatisch für alle API-Anfragen der Anwendung wiederverwendet. Sie müssen nicht für jede API-Anfrage eine neue erstellen.

ILogger

Wenn Sie bereits einen ILogger für Ihre Anwendungsprotokolle verwenden, können Sie mit dieser Lösung Google Ads API-Protokolle in Ihre vorhandene Logging-Infrastruktur einbinden.

Erstellen Sie zuerst eine LoggerFactory oder fügen Sie die Filter für Google Ads API-Logs hinzu, falls Sie bereits eine haben:

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

Verwenden Sie dann LoggerFactory, um Logger für Zusammenfassungen und Details von Anfragen und Antworten zu erstellen:

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

Konfigurieren Sie schließlich die Clientbibliothek so, dass ihre Traces an Ihre ILogger-Instanzen weitergeleitet werden:

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

Mit dieser Lösung können Sie API-Anfrage- und Antwortprotokolle der Google Ads API in vorhandene Logging-Frameworks wie Log4Net, NLog und Serilog einbinden.

Logebenen

Die Bibliothek protokolliert verschiedene Arten von Ereignissen auf unterschiedlichen Protokollierungsebenen:

• Erfolgreiche API-Antwort: Die Zusammenfassung wird unter INFO protokolliert. Die vollständige Anfrage und Antwort werden unter DEBUG protokolliert.
• API-Fehlerantwort: Die Zusammenfassung wird unter WARN geloggt. Die vollständige Anfrage und Antwort werden unter INFO geloggt.
• Teilweise fehlgeschlagene Vorgänge: Protokolliert unter DEBUG.

Anfrage-ID

In den meisten Fällen enthalten die von der Clientbibliothek generierten Logs genügend Details, um Probleme zu beheben. Wenn Sie sich an den Support wenden, stellen Sie entweder die Logs bereit (in denen vertrauliche Authentifizierungsfelder standardmäßig unkenntlich gemacht werden) oder geben Sie die Anfrage-ID an, die im Antwortlog protokolliert wird.

Wenn Sie die Anfrage-ID lieber programmatisch erfassen möchten, verwenden Sie einen der folgenden Ansätze.

Aus gewöhnlichen unären API-Aufrufen extrahieren

Sie können einen benutzerdefinierten CallSettings mit einem TrailingMetadataHandler verwenden, um Anfrage-IDs aus regulären unären Aufrufen zu erfassen:

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

Aus Streaming-API-Aufrufen extrahieren

Die Anfrage-ID wird als Teil des Antwortobjekts für Streaming-API-Aufrufe zurückgegeben. So können Sie beispielsweise die Anfrage-ID für einen SearchStream-Aufruf abrufen:

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

Ausnahmen

Die Anfrage-ID wird als Teil der Ausnahme GoogleAdsException zurückgegeben, wenn ein API-Aufruf fehlschlägt:

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

Erweitertes Logging konfigurieren

Wenn das API-Log nicht genügend Details enthält, aktivieren Sie das Logging auf niedrigerer Ebene auf der gRPC-Transportebene. Beachten Sie, dass die Ausgabe sehr umfangreich sein kann.

Wenn Sie den Standardtransport Grpc.Net.Client verwenden, konfigurieren Sie Logs auf Transportebene über den ILogger-Anbieter von .NET. Fügen Sie dazu einen Filter für die Kategorie Grpc hinzu (z. B. builder.AddFilter("Grpc", LogLevel.Debug)).

Wenn Sie den Legacy-Grpc.Core-Transport (UseGrpcCore = true) verwenden, werden gRPC-Logs standardmäßig in stderr geschrieben. Sie können aber auch einen eigenen Logger anhängen, wie im folgenden Beispiel gezeigt. Weitere Informationen finden Sie unter Unterstützte gRPC-Umgebungsvariablen.

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

TraceListener-Konfiguration mit App.config (Legacy)

Wenn Ihre Anwendung für ein .NET Framework-Ziel erstellt wird, können Sie die Logging-Konfiguration aus der Datei App.config oder Web.config Ihrer Anwendung laden. Dies ist eine Legacy-.NET-Funktion, die für Anwendungen, die für moderne .NET-Ziele erstellt wurden, nicht unterstützt wird.

Wenn Sie diese Funktion verwenden möchten, fügen Sie Ihrer Konfigurationsdatei die folgenden Änderungen hinzu:

1. Fügen Sie das folgende Snippet im Abschnitt <configuration> hinzu:

   <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. Fügen Sie das folgende Snippet im Abschnitt <configSections> hinzu:

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

   Ihre App.config sieht dann so aus:

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