ロギングを構成する

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

TraceListener

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

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

アプリケーション ログに ILogger をすでに使用している場合は、このソリューションを使用すると、Google Ads API ログを既存のロギング インフラストラクチャに統合できます。

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

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

次に、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 を使用してカスタム CallSettings を使用すると、通常の単項呼び出しからリクエスト ID をキャプチャできます。

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

ストリーミング API 呼び出しから抽出する

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

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

例外

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

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

高度なロギングを構成する

API ログで十分な詳細情報が得られない場合は、gRPC トランスポート レベルで下位レベルのロギングを有効にします。出力が大量になる可能性があることに注意してください。

デフォルトの Grpc.Net.Client トランスポートを使用する場合は、Grpc カテゴリ（builder.AddFilter("Grpc", LogLevel.Debug) など）のフィルタを追加して、.NET の ILogger プロバイダを介してトランスポート レベルのログを構成します。

以前の Grpc.Core トランスポート（UseGrpcCore = true）を使用している場合、gRPC ログはデフォルトで stderr に書き込まれます。次の例に示すように、独自のロガーを接続することもできます。詳細については、サポートされている gRPC 環境変数をご覧ください。

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 機能です。

この機能を使用するには、構成ファイルに次の変更を加えます。

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