ロギング

警告: バージョン 19.0.0 以降、.NET 用 Google Ads API クライアント ライブラリは .NET 5.0 をサポートしなくなります。シームレスな運用を確保するため、2024 年末までに .NET バージョンをアップグレードすることを強くおすすめします。

.NET クライアント ライブラリは、Google Ads API に対して行われたリクエスト、レスポンス、概要メッセージをログに記録します。ログは、カスタム TraceListener またはカスタム ILogger インスタンスに書き込むことができます。

TraceListener

TraceListener へのロギングを有効にするには、API 呼び出しを行う前に Main メソッドに次の行を追加します。

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

ILogger

アプリケーション ログに ILogger をすでに使用している場合は、このソリューションを使用して、Google Ads API ログを既存のログに統合できます。

まず、LoggerFactory を作成します。すでに作成している場合は、Google Ads API ログのフィルタを追加します。

var loggerFactory = LoggerFactory.Create(delegate (ILoggingBuilder builder)
{
  // Log to stdout.
  builder.AddConsole();
  builder.AddFilter(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE, LogLevel.Trace);
  builder.AddFilter(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE, LogLevel.Trace);
});

次に、LoggerFactory を使用して、リクエストとレスポンスの概要と詳細のロガーを作成します。

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

最後に、トレース内容を ILogger インスタンスにリダイレクトするようにクライアント ライブラリを構成します。

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

このソリューションを使用すると、Google Ads API のリクエストログとレスポンスログを、Log4Net、NLog、Serilog などの既存のロギング フレームワークに統合できます。

ログレベル

ライブラリは、さまざまなタイプのイベントをさまざまなログレベルにロギングします。正常な API レスポンスの場合、概要は INFO に、リクエストとレスポンスの完全な内容は DEBUG にログに記録されます。

API エラーが発生したリクエストでは、概要メッセージが WARN にログに記録され、リクエストとレスポンスの全体が INFO にログに記録されます。

部分的な失敗は DEBUG に記録されます。

リクエスト ID

ほとんどの場合、クライアント ライブラリによって生成されたログには、問題のトラブルシューティングに十分な詳細情報が含まれています。サポート フォーラム/エイリアスに問い合わせる際は、ログ（デフォルトで機密情報が除去されます）を提供するか、リクエスト ID（レスポンス ログの一部としてロギングされます）を共有してください。

リクエスト ID を自分で取得する場合は、次のいずれかの方法を使用できます。

通常の API 呼び出しによる抽出

TrailingMetadataHandler でカスタム CallSetting を使用すると、通常の単項呼び出しからリクエスト ID を取得できます。

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

ストリーミング API 呼び出しによる抽出

リクエスト ID は、ストリーミング API 呼び出しのレスポンス オブジェクトの一部として返されます。たとえば、SearchStream 呼び出しのリクエスト ID は次のように取得できます。

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V19.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);
        }
    }
);

例外

リクエスト ID は、API 呼び出しが失敗するたびに GoogleAdsException 例外の一部として返されます。

try
{
  // Make an API call.
  ...
}
catch (GoogleAdsException e)
{
    string requestId = e.RequestId;
}

高度なロギング

API ログに十分な詳細情報がない場合は、gRPC レベルでより低レベルのロギングを有効にします。出力は大量になる可能性があることに注意してください。gRPC ログは stderr に書き込まれますが、次のように独自のロガーを接続できます。サポートされている環境変数。

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

App.config を使用した TraceListener の構成（従来版）

アプリが .NET Framework ターゲット用にビルドされている場合は、アプリの App.config ファイルまたは Web.config ファイルからロギング構成を読み込むことができます。これは以前の .NET 機能であり、.NET Core ターゲット用にビルドされたアプリではサポートされていません。

この機能を使用するには、構成ファイルに次の変更を追加する必要があります。

1. <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. <configSections> セクションの下に次のスニペットを追加します。

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

   App.config は次のようになります。

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