.NET のログとトレースの相関付け

Docs > APM > APM データと他のテレメトリーとの相関付け > ログとトレースの相関 > .NET のログとトレースの相関付け

トレースとスパンの ID がアプリケーションログに挿入されるようロギングライブラリおよび .NET トレーシングの構成を設定し、ログデータと相関したアプリケーションのパフォーマンスモニタリングデータを取得することができます。

.NET トレーサーを Unified Service Tagging で構成して、アプリケーションのトレースとログの相関付けに最高の使用体験と有用なコンテキストを確保します。

.NET トレーサーは、以下のロギングライブラリをサポートします。

Serilog (v1.4+)
log4net
NLog
Microsoft.Extensions.Logging (v1.28.6 で追加)

ログ収集の構成

Datadog Agent でログ収集が構成されていること、またログパイプラインがログファイルを解析できるように、追跡する指定ファイルのログ Agent の構成が source: csharp に設定されていることを確認します。詳細については、C# ログ収集を参照してください。source が csharp 以外の値に設定されている場合、相関を正しく動作させるために、適切なログ処理パイプラインにトレースリマッパーを追加する必要があるかもしれません。

自動ログ収集は、JSON 形式のログにのみ対応しています。カスタムパースルールを使用することもできます。

ログへの挿入の構成

ログメッセージに相関識別子を挿入するには、お使いのロギングライブラリの指示に従ってください。

その他の例については、dd-trace-dotnet にあるサンプルを参照してください。

注: .NET トレーサーバージョン 2.0.1 以降、Serilog ロギングライブラリの自動挿入には、アプリケーションが自動インスツルメンテーションされているれていることが必要になります。

ログメッセージに相関識別子を自動的に挿入するには:

以下のトレーサー設定で .NET トレーサーを構成します。
- DD_ENV
- DD_SERVICE
- DD_VERSION
.NET トレーサーのインストール手順に従って、アプリの自動インスツルメンテーショントレーシングを有効にします。

注: .NET トレーサーバージョン 1.29.0 以降、log4net ロギングライブラリの自動挿入には、アプリケーションが自動インスツルメンテーションされているれていることが必要になります。

ログメッセージに相関識別子を自動的に挿入するには:

以下のトレーサー設定で .NET トレーサーを構成します。
- DD_ENV
- DD_SERVICE
- DD_VERSION
.NET トレーサーのインストール手順に従って、アプリの自動インスツルメンテーショントレーシングを有効にします。
ログ出力に dd.env、dd.service、dd.version、dd.trace_id、dd.span_id のログプロパティを追加してください。これらのプロパティを_個別に_含めることもできますし、_すべての_ログプロパティを含めることもできます。どちらの方法も、次のサンプルコードに示されています。

  <layout type="log4net.Layout.SerializedLayout, log4net.Ext.Json">
    <decorator type="log4net.Layout.Decorators.StandardTypesDecorator, log4net.Ext.Json" />
    <default />
    <!--explicit default members-->
    <remove value="ndc" />
    <!--remove the default preformatted message member-->
    <remove value="message" />
    <!--add raw message-->
    <member value="message:messageobject" />

    <!-- Include Datadog properties -->
    <!-- EITHER Include individual properties with value='<property_name>' -->
    <member value='dd.env' />
    <member value='dd.service' />
    <member value='dd.version' />
    <member value='dd.trace_id' />
    <member value='dd.span_id' />
    <!-- OR Include all properties with value='properties' -->
    <member value='properties'/>
  </layout>

その他の例については、GitHub の log4net トレース ID 自動挿入プロジェクトを参照してください。

注: .NET トレーサーバージョン 2.0.1 以降、NLog ロギングライブラリの自動挿入には、アプリケーションが自動インスツルメンテーションされているれていることが必要になります。

ログメッセージに相関識別子を自動的に挿入するには:

以下のトレーサー設定で .NET トレーサーを構成します。
- DD_ENV
- DD_SERVICE
- DD_VERSION
.NET トレーサーのインストール手順に従って、アプリの自動インスツルメンテーショントレーシングを有効にします。
次の NLog バージョン 5.0 以降向けのサンプルコードに示すように、マップされた診断コンテキスト (MDC) を有効にします。

  <!-- Add includeScopeProperties="true" to emit ScopeContext properties -->
  <layout xsi:type="JsonLayout" includeScopeProperties="true">
    <attribute name="date" layout="${longdate}" />
    <attribute name="level" layout="${level:upperCase=true}"/>
    <attribute name="message" layout="${message}" />
    <attribute name="exception" layout="${exception:format=ToString}" />
  </layout>

NLog バージョン 4.6 以降の場合

  <!-- Add includeMdlc="true" to emit MDC properties -->
  <layout xsi:type="JsonLayout" includeMdlc="true">
    <attribute name="date" layout="${longdate}" />
    <attribute name="level" layout="${level:upperCase=true}"/>
    <attribute name="message" layout="${message}" />
    <attribute name="exception" layout="${exception:format=ToString}" />
  </layout>

NLog バージョン 4.5 の場合

  <!-- Add includeMdc="true" to emit MDC properties -->
  <layout xsi:type="JsonLayout" includeMdc="true">
    <attribute name="date" layout="${longdate}" />
    <attribute name="level" layout="${level:upperCase=true}"/>
    <attribute name="message" layout="${message}" />
    <attribute name="exception" layout="${exception:format=ToString}" />
  </layout>

その他の例については、GitHub で NLog 4.0、NLog 4.5、NLog 4.6 を使用したトレース ID 自動挿入プロジェクトを参照してください。

ログメッセージに相関識別子を自動的に挿入するには:

以下のトレーサー設定で .NET トレーサーを構成します。
- DD_ENV
- DD_SERVICE
- DD_VERSION
.NET トレーサーのインストール手順に従って、アプリの自動インスツルメンテーショントレーシングを有効にします。
サンプルコードに示するように、お使いのロギングプロバイダーのログスコープを有効にします。ログスコープをサポートしているプロバイダーにのみ、相関識別子が挿入されます。

Host.CreateDefaultBuilder(args)
    .ConfigureLogging(logging =>
    {
        logging.AddFile(opts =>
        {
            opts.IncludeScopes = true; // must include scopes so that correlation identifiers are added
            opts.FormatterName = "json";
        });
    }

ログが書き込まれているときにアクティブなトレースがあれば、トレース ID とスパン ID が dd_trace_id プロパティと dd_span_id プロパティにより自動的にアプリケーションログに挿入されます。アクティブなトレースがない場合は、dd_env、dd_service、dd_version プロパティのみが挿入されます。

注: Serilog.Extensions.Hosting パッケージや Serilog.Extensions.Logging パッケージのように、デフォルトの LoggerFactory の実装を置き換えるロギングライブラリを使用している場合は、フレームワーク固有の指示に従ってください (この例では、Serilog を参照してください)。

その他の例については、GitHub の Microsoft.Extensions.Logging トレース ID 自動挿入プロジェクトを参照してください。

次に、自動挿入または手動挿入のセットアップを完了します。

自動挿入

相関識別子の自動挿入を有効にするには、DD_LOGS_INJECTION が有効であることを確認してください。

バージョン 3.24.0 以降、DD_LOGS_INJECTION はデフォルトで有効になっています。それより前のバージョンでは、.NET トレーサーの環境変数に DD_LOGS_INJECTION=true を設定してください。

.NET トレーサーを構成する別の方法については、.NET トレーサーの構成を参照してください。

相関識別子の挿入を構成した後、C# ログ収集を参照して、ログ収集の構成を行います。

注: トレースとログを関連付けるには、ログのトレース ID として dd_trace_id をパースするトレース ID リマッパーをセットアップする必要があるかもしれません。詳しくは、関連するログがトレース ID パネルに表示されないを参照してください。

バージョン 2.35.0 以降、このサービスが実行される環境で Agent Remote Configuration が有効になっている場合は、 DD_LOGS_INJECTION を Catalog UI で設定できます。

手動挿入

トレースとログを手動で相関させたい場合は、ログに相関識別子を追加することができます。

必要なキー	説明
`dd.env`	SDK の `env` をグローバルに構成します。設定されていない場合は、デフォルトで `""` になります。
`dd.service`	ルートサービス名をグローバルに構成します。設定されていない場合は、デフォルトでアプリケーション名または IIS サイト名になります。
`dd.version`	サービスの `version` をグローバルに構成します。設定されていない場合は、デフォルトで `""` になります。
`dd.trace_id`	ログステートメント中のアクティブなトレース ID (64 ビットの 10 進数として表現)。トレースがない場合は、デフォルトで `0` になります。
`dd.span_id`	ログステートメント中のアクティブなスパン ID (64 ビットの 10 進数として表現)。トレースがない場合は、デフォルトで `0` になります。

注: Datadog ログインテグレーションを使用してログをパースしていない場合、カスタムログパースルールによって dd.trace_id と dd.span_id が文字列としてパースされる必要があります。詳しくは、関連するログがトレース ID パネルに表示されないを参照してください。

注: ILogger を通して Serilog、NLog、log4net を使用している場合、BeginScope() を使用してこれらのプロパティを構成するには、Microsoft.Extensions.Logging のセクションを参照してください。

はじめのステップが完了したら、手動のログエンリッチメント設定を完了してください。

プロジェクトの Datadog.Trace NuGet パッケージを参照します。
CorrelationIdentifier API を使用して相関識別子を取得し、スパンがアクティブな間にログのコンテキストに追加します。

最後に、C# ログ収集を参照して、ログ収集を構成します。

例:

注: Serilog ライブラリでは、メッセージプロパティ名が有効な C# 識別子である必要があります。必要なプロパティ名は、dd_env、dd_service、dd_version、dd_trace_id、および dd_span_id です。

using Datadog.Trace;
using Serilog.Context;

// there must be spans started and active before this block.
using (LogContext.PushProperty("dd_env", CorrelationIdentifier.Env))
using (LogContext.PushProperty("dd_service", CorrelationIdentifier.Service))
using (LogContext.PushProperty("dd_version", CorrelationIdentifier.Version))
using (LogContext.PushProperty("dd_trace_id", CorrelationIdentifier.TraceId.ToString()))
using (LogContext.PushProperty("dd_span_id", CorrelationIdentifier.SpanId.ToString()))
{
    // Log something
}

using Datadog.Trace;
using log4net;

// there must be spans started and active before this block.
try
{
    LogicalThreadContext.Properties["dd.env"] = CorrelationIdentifier.Env;
    LogicalThreadContext.Properties["dd.service"] = CorrelationIdentifier.Service;
    LogicalThreadContext.Properties["dd.version"] = CorrelationIdentifier.Version;
    LogicalThreadContext.Properties["dd.trace_id"] = CorrelationIdentifier.TraceId.ToString();
    LogicalThreadContext.Properties["dd.span_id"] = CorrelationIdentifier.SpanId.ToString();

    // Log something

}
finally
{
    LogicalThreadContext.Properties.Remove("dd.env");
    LogicalThreadContext.Properties.Remove("dd.service");
    LogicalThreadContext.Properties.Remove("dd.version");
    LogicalThreadContext.Properties.Remove("dd.trace_id");
    LogicalThreadContext.Properties.Remove("dd.span_id");
}

using Datadog.Trace;
using NLog;

// there must be spans started and active before this block.
using (MappedDiagnosticsLogicalContext.SetScoped("dd.env", CorrelationIdentifier.Env))
using (MappedDiagnosticsLogicalContext.SetScoped("dd.service", CorrelationIdentifier.Service))
using (MappedDiagnosticsLogicalContext.SetScoped("dd.version", CorrelationIdentifier.Version))
using (MappedDiagnosticsLogicalContext.SetScoped("dd.trace_id", CorrelationIdentifier.TraceId.ToString()))
using (MappedDiagnosticsLogicalContext.SetScoped("dd.span_id", CorrelationIdentifier.SpanId.ToString()))
{
    // Log something
}

using Datadog.Trace;
using Microsoft.Extensions.Logging;

ILogger _logger;

// there must be spans started and active before this block.
using(_logger.BeginScope(new Dictionary<string, object>
{
    {"dd.env", CorrelationIdentifier.Env},
    {"dd.service", CorrelationIdentifier.Service},
    {"dd.version", CorrelationIdentifier.Version},
    {"dd.trace_id", CorrelationIdentifier.TraceId.ToString()},
    {"dd.span_id", CorrelationIdentifier.SpanId.ToString()},
}))
{
    // Log something
}