로깅 구성

.NET 클라이언트 라이브러리는 Google Ads API에 대한 요청, 응답, 요약 메시지를 로깅합니다. 로그는 커스텀 TraceListener 또는 커스텀 ILogger 인스턴스에 작성할 수 있습니다.

TraceListener

API를 호출하기 전에 Main 메서드에 다음 줄을 추가하여 TraceListener에 로깅을 사용 설정할 수 있습니다.

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

예외

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 전송을 사용하는 경우 .NET의 ILogger 제공자를 통해 전송 수준 로그를 구성하여 Grpc 카테고리의 필터를 추가합니다 (예: builder.AddFilter("Grpc", LogLevel.Debug)).

레거시 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>